@ran-sh/dsh-crew 1.8.0 → 1.9.1

package/src/job-contracts.mjs

@@ -1,255 +1,255 @@
-// Versioned, transport-neutral contracts for one DSH Crew workflow.
-//
-// The workflow runtime may keep richer internal state for recovery and debug,
-// but callers receive this bounded event/evidence layer by default. Full
-// internal details remain available only through an explicit detail=full
-// request at the MCP boundary.
-
-export const JOB_CONTRACT_SCHEMA_VERSION = 1;
-
-export const JOB_EVENT_TYPES = Object.freeze([
-  'job.created',
-  'job.started',
-  'runtime.bound',
-  'model.selected',
-  'model.admitted',
-  'agent.created',
-  'model.fallback',
-  'worker.started',
-  'worker.completed',
-  'review.started',
-  'review.completed',
-  'approval.required',
-  'job.completed',
-  'job.failed',
-  'job.cancelled',
-]);
-
-const EVENT_TYPE_SET = new Set(JOB_EVENT_TYPES);
-const RESULT_STATUSES = Object.freeze(['PASS', 'FAIL', 'PARTIAL', 'BLOCKED']);
-
-function boundedText(value, limit = 800) {
-  if (value == null) return null;
-  const text = String(value).trim();
-  if (!text) return null;
-  return text.length <= limit ? text : `${text.slice(0, limit)}…`;
-}
-
-function boundedStrings(values, { count = 80, length = 400 } = {}) {
-  if (!Array.isArray(values)) return [];
-  return values.slice(0, count)
-    .map((value) => boundedText(value, length))
-    .filter(Boolean);
-}
-
-function boundedTests(values) {
-  if (!Array.isArray(values)) return [];
-  return values.slice(0, 40).map((test) => ({
-    status: RESULT_STATUSES.includes(test?.status) ? test.status : boundedText(test?.status, 40),
-    command: boundedText(test?.command, 300),
-    summary: boundedText(test?.summary, 500),
-  }));
-}
-
-/** Create one canonical, monotonically sequenced workflow event. */
-export function createCanonicalJobEvent({
-  jobId,
-  type,
-  sequence,
-  at,
-  role = null,
-  attempt = null,
-  data = {},
-} = {}) {
-  if (!EVENT_TYPE_SET.has(type)) throw new Error(`unknown canonical job event: ${String(type)}`);
-  if (typeof jobId !== 'string' || !jobId) throw new Error('canonical job event requires jobId');
-  if (!Number.isInteger(sequence) || sequence < 1) throw new Error('canonical job event requires a positive sequence');
-  return {
-    schema_version: JOB_CONTRACT_SCHEMA_VERSION,
-    event_id: `${jobId}:${sequence}`,
-    job_id: jobId,
-    sequence,
-    type,
-    at,
-    role,
-    attempt,
-    data: data && typeof data === 'object' && !Array.isArray(data) ? { ...data } : {},
-  };
-}
-
-function evidenceStatus(view) {
-  if (view?.status === 'cancelled' || view?.phase === 'cancelled') return 'BLOCKED';
-  if (view?.status === 'failed' || view?.phase === 'failed' || view?.outcome?.execution_status === 'failed') return 'FAIL';
-  if (view?.review?.verdict === 'request_changes' || view?.outcome?.task_status === 'partial') return 'PARTIAL';
-  if (view?.outcome?.task_status === 'blocked') return 'BLOCKED';
-  if (view?.role === 'reviewer' && view?.outcome == null) {
-    return view.status === 'done' && view.review?.status === 'done'
-      && view.review.verdict === 'approve' && view.review.delivery_complete === true
-      && view.review.mutated_candidate !== true ? 'PASS' : 'PARTIAL';
-  }
-  if (view?.status === 'done' && view?.outcome?.task_status === 'success') return 'PASS';
-  return 'PARTIAL';
-}
-
-function compactSelectionTrace(attempts) {
-  if (!Array.isArray(attempts)) return [];
-  return attempts.slice(0, 16).map((attempt) => {
-    const trace = attempt?.selection_trace ?? {};
-    const rawSelected = trace.selected ?? (
-      attempt?.provider || attempt?.model
-        ? { provider: attempt?.provider ?? null, model: attempt?.model ?? null, source: attempt?.selection_source ?? null }
-        : null
-    );
-    const selected = rawSelected ? {
-      provider: boundedText(rawSelected.provider, 200),
-      model: boundedText(rawSelected.model, 300),
-      source: boundedText(rawSelected.source, 100),
-    } : null;
-    const candidates = Array.isArray(trace.ordered_candidates)
-      ? trace.ordered_candidates.slice(0, 32).map((candidate) => ({
-        model: boundedText(candidate?.model, 300),
-        provider: boundedText(candidate?.provider, 200),
-        status: String(candidate?.status ?? 'CANDIDATE').toUpperCase(),
-        ...(candidate?.reason ? { reason: boundedText(candidate.reason, 200) } : {}),
-      }))
-      : selected ? [{ model: selected.model ?? null, provider: selected.provider ?? null, status: 'SELECTED' }] : [];
-    return {
-      attempt: attempt?.attempt ?? null,
-      role: attempt?.role ?? null,
-      selected,
-      selected_model: selected?.model ?? null,
-      candidates,
-      fallback_chain: trace.fallback_reason ? [boundedText(trace.fallback_reason, 200)] : [],
-      decision_reason: boundedText(selected?.source ?? attempt?.selection_source, 200),
-      fallback_reason: boundedText(trace.fallback_reason, 200),
-      escalation_reason: boundedText(trace.escalation_reason, 200),
-    };
-  });
-}
-
-function changedFilesFromView(view) {
-  if (Array.isArray(view?.candidate?.changed_files)) return view.candidate.changed_files;
-  const changes = view?.workspace_diff?.changes;
-  if (!changes || typeof changes !== 'object') return [];
-  return [...new Set([
-    ...(Array.isArray(changes.modified) ? changes.modified : []),
-    ...(Array.isArray(changes.deleted) ? changes.deleted : []),
-    ...(Array.isArray(changes.renamed) ? changes.renamed : []),
-    ...(Array.isArray(changes.untracked) ? changes.untracked : []),
-  ])];
-}
-
-function boundedExecutionContext(value) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-  const executionPlane = boundedText(value.execution_plane, 64);
-  const profile = boundedText(value.profile, 64);
-  const runtimeId = boundedText(value.runtime_id, 128);
-  const port = Number.isInteger(value.listen_port) ? value.listen_port : null;
-  const ingress = value.ingress === 'official-3080' || value.ingress === 'direct-3210' ? value.ingress : null;
-  if (!executionPlane && !profile && !runtimeId && port === null && !ingress) return null;
-  return {
-    execution_plane: executionPlane,
-    profile,
-    listen_port: port,
-    runtime_id: runtimeId,
-    ...(ingress ? { ingress } : {}),
-  };
-}
-
-/**
- * Build the machine-first Result Contract for a workflow.
- *
- * Deliberately excluded: worker prose, raw provider payloads and candidate
- * patch text. The envelope contains enough evidence for orchestration while
- * artifact inspection remains an explicit follow-up operation.
- */
-export function buildEvidenceEnvelope(view = {}) {
-  const outcome = view.outcome ?? {};
-  const candidate = view.candidate ?? {};
-  const review = view.review ?? null;
-  const errorMessage = boundedText(view.error, 1000);
-  const changedFiles = boundedStrings(changedFilesFromView(view), { count: 120, length: 500 });
-  const status = evidenceStatus(view);
-  const reviewOnly = view.role === 'reviewer' && view.outcome == null;
-  const selectionAttempts = Array.isArray(view.child_attempts) && view.child_attempts.length > 0
-    ? view.child_attempts
-    : (view.selection_trace || view.provider || view.model ? [view] : []);
-  return {
-    schema_version: JOB_CONTRACT_SCHEMA_VERSION,
-    job_id: view.id ?? null,
-    client_job_id: view.client_job_id ?? null,
-    role: view.role ?? null,
-    status,
-    summary: {
-      phase: view.phase ?? null,
-      task_status: outcome.task_status ?? (reviewOnly && status === 'PASS' ? 'success' : null),
-      execution_status: outcome.execution_status ?? (reviewOnly && review?.status === 'done' ? 'completed' : null),
-      tests_status: outcome.tests_status ?? null,
-      delivery_complete: reviewOnly ? review?.delivery_complete === true : outcome.delivery?.complete === true,
-      review_verdict: review?.verdict ?? null,
-    },
-    selection_trace: compactSelectionTrace(selectionAttempts),
-    execution_context: boundedExecutionContext(view.execution_context ?? selectionAttempts[0]?.execution_context),
-    changed_files: changedFiles,
-    changes: boundedStrings(outcome.changes),
-    tests: boundedTests(outcome.tests),
-    risks: boundedStrings(reviewOnly ? review?.risks : outcome.risks),
-    unverified: boundedStrings(outcome.unverified),
-    review: review ? {
-      verdict: review.verdict ?? null,
-      status: review.status ?? null,
-      findings: boundedStrings(review.findings),
-      evidence: boundedStrings(review.evidence),
-      risks: boundedStrings(review.risks),
-      delivery_complete: review.delivery_complete === true,
-      mutated_candidate: review.mutated_candidate === true,
-    } : null,
-    artifacts: {
-      candidate_available: view.candidate_available === true || changedFiles.length > 0,
-      candidate_fingerprint: candidate.fingerprint ?? null,
-      base_revision: candidate.base_revision ?? view.base_revision ?? null,
-      workspace_retained: view.workspace_retained === true,
-      candidate_capture_failed: view.candidate_capture_failed === true,
-    },
-    errors: errorMessage || view.error_code ? [{ code: view.error_code ?? null, message: errorMessage }] : [],
-  };
-}
-
-/** Project a rich internal workflow view onto compact or explicit full detail. */
-export function projectWorkflowView(view, { detail = 'compact', afterSequence = 0 } = {}) {
-  if (!view || typeof view !== 'object') return view;
-  const evidence = buildEvidenceEnvelope(view);
-  const allCanonical = Array.isArray(view.canonical_events) ? view.canonical_events : [];
-  const cursor = allCanonical.at(-1)?.sequence ?? view.event_cursor ?? 0;
-  const canonicalEvents = allCanonical.filter((event) => Number(event?.sequence) > afterSequence);
-  const eventProjection = {
-    canonical_events: canonicalEvents,
-    event_cursor: cursor,
-    events_truncated_before_cursor: afterSequence > 0 && canonicalEvents.length > 0
-      ? canonicalEvents[0].sequence !== afterSequence + 1
-      : false,
-  };
-  if (detail === 'full') return { ...view, ...eventProjection, detail: 'full', evidence };
-
-  const {
-    candidate: _candidate,
-    outcome: _outcome,
-    review: _review,
-    events: _legacyEvents,
-    child_attempts: _childAttempts,
-    selection_trace: _rawSelectionTrace,
-    selection_source: _rawSelectionSource,
-    result: _rawResult,
-    workspace_diff: _workspaceDiff,
-    reasonDetail: _reasonDetail,
-    ...safe
-  } = view;
-  return {
-    ...safe,
-    ...eventProjection,
-    error: boundedText(view.error, 1000),
-    cleanup_warning: boundedText(view.cleanup_warning, 1000),
-    detail: 'compact',
-    evidence,
-  };
-}
+// Versioned, transport-neutral contracts for one DSH Crew workflow.
+//
+// The workflow runtime may keep richer internal state for recovery and debug,
+// but callers receive this bounded event/evidence layer by default. Full
+// internal details remain available only through an explicit detail=full
+// request at the MCP boundary.
+
+export const JOB_CONTRACT_SCHEMA_VERSION = 1;
+
+export const JOB_EVENT_TYPES = Object.freeze([
+  'job.created',
+  'job.started',
+  'runtime.bound',
+  'model.selected',
+  'model.admitted',
+  'agent.created',
+  'model.fallback',
+  'worker.started',
+  'worker.completed',
+  'review.started',
+  'review.completed',
+  'approval.required',
+  'job.completed',
+  'job.failed',
+  'job.cancelled',
+]);
+
+const EVENT_TYPE_SET = new Set(JOB_EVENT_TYPES);
+const RESULT_STATUSES = Object.freeze(['PASS', 'FAIL', 'PARTIAL', 'BLOCKED']);
+
+function boundedText(value, limit = 800) {
+  if (value == null) return null;
+  const text = String(value).trim();
+  if (!text) return null;
+  return text.length <= limit ? text : `${text.slice(0, limit)}…`;
+}
+
+function boundedStrings(values, { count = 80, length = 400 } = {}) {
+  if (!Array.isArray(values)) return [];
+  return values.slice(0, count)
+    .map((value) => boundedText(value, length))
+    .filter(Boolean);
+}
+
+function boundedTests(values) {
+  if (!Array.isArray(values)) return [];
+  return values.slice(0, 40).map((test) => ({
+    status: RESULT_STATUSES.includes(test?.status) ? test.status : boundedText(test?.status, 40),
+    command: boundedText(test?.command, 300),
+    summary: boundedText(test?.summary, 500),
+  }));
+}
+
+/** Create one canonical, monotonically sequenced workflow event. */
+export function createCanonicalJobEvent({
+  jobId,
+  type,
+  sequence,
+  at,
+  role = null,
+  attempt = null,
+  data = {},
+} = {}) {
+  if (!EVENT_TYPE_SET.has(type)) throw new Error(`unknown canonical job event: ${String(type)}`);
+  if (typeof jobId !== 'string' || !jobId) throw new Error('canonical job event requires jobId');
+  if (!Number.isInteger(sequence) || sequence < 1) throw new Error('canonical job event requires a positive sequence');
+  return {
+    schema_version: JOB_CONTRACT_SCHEMA_VERSION,
+    event_id: `${jobId}:${sequence}`,
+    job_id: jobId,
+    sequence,
+    type,
+    at,
+    role,
+    attempt,
+    data: data && typeof data === 'object' && !Array.isArray(data) ? { ...data } : {},
+  };
+}
+
+function evidenceStatus(view) {
+  if (view?.status === 'cancelled' || view?.phase === 'cancelled') return 'BLOCKED';
+  if (view?.status === 'failed' || view?.phase === 'failed' || view?.outcome?.execution_status === 'failed') return 'FAIL';
+  if (view?.review?.verdict === 'request_changes' || view?.outcome?.task_status === 'partial') return 'PARTIAL';
+  if (view?.outcome?.task_status === 'blocked') return 'BLOCKED';
+  if (view?.role === 'reviewer' && view?.outcome == null) {
+    return view.status === 'done' && view.review?.status === 'done'
+      && view.review.verdict === 'approve' && view.review.delivery_complete === true
+      && view.review.mutated_candidate !== true ? 'PASS' : 'PARTIAL';
+  }
+  if (view?.status === 'done' && view?.outcome?.task_status === 'success') return 'PASS';
+  return 'PARTIAL';
+}
+
+function compactSelectionTrace(attempts) {
+  if (!Array.isArray(attempts)) return [];
+  return attempts.slice(0, 16).map((attempt) => {
+    const trace = attempt?.selection_trace ?? {};
+    const rawSelected = trace.selected ?? (
+      attempt?.provider || attempt?.model
+        ? { provider: attempt?.provider ?? null, model: attempt?.model ?? null, source: attempt?.selection_source ?? null }
+        : null
+    );
+    const selected = rawSelected ? {
+      provider: boundedText(rawSelected.provider, 200),
+      model: boundedText(rawSelected.model, 300),
+      source: boundedText(rawSelected.source, 100),
+    } : null;
+    const candidates = Array.isArray(trace.ordered_candidates)
+      ? trace.ordered_candidates.slice(0, 32).map((candidate) => ({
+        model: boundedText(candidate?.model, 300),
+        provider: boundedText(candidate?.provider, 200),
+        status: String(candidate?.status ?? 'CANDIDATE').toUpperCase(),
+        ...(candidate?.reason ? { reason: boundedText(candidate.reason, 200) } : {}),
+      }))
+      : selected ? [{ model: selected.model ?? null, provider: selected.provider ?? null, status: 'SELECTED' }] : [];
+    return {
+      attempt: attempt?.attempt ?? null,
+      role: attempt?.role ?? null,
+      selected,
+      selected_model: selected?.model ?? null,
+      candidates,
+      fallback_chain: trace.fallback_reason ? [boundedText(trace.fallback_reason, 200)] : [],
+      decision_reason: boundedText(selected?.source ?? attempt?.selection_source, 200),
+      fallback_reason: boundedText(trace.fallback_reason, 200),
+      escalation_reason: boundedText(trace.escalation_reason, 200),
+    };
+  });
+}
+
+function changedFilesFromView(view) {
+  if (Array.isArray(view?.candidate?.changed_files)) return view.candidate.changed_files;
+  const changes = view?.workspace_diff?.changes;
+  if (!changes || typeof changes !== 'object') return [];
+  return [...new Set([
+    ...(Array.isArray(changes.modified) ? changes.modified : []),
+    ...(Array.isArray(changes.deleted) ? changes.deleted : []),
+    ...(Array.isArray(changes.renamed) ? changes.renamed : []),
+    ...(Array.isArray(changes.untracked) ? changes.untracked : []),
+  ])];
+}
+
+function boundedExecutionContext(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const executionPlane = boundedText(value.execution_plane, 64);
+  const profile = boundedText(value.profile, 64);
+  const runtimeId = boundedText(value.runtime_id, 128);
+  const port = Number.isInteger(value.listen_port) ? value.listen_port : null;
+  const ingress = value.ingress === 'official-3080' || value.ingress === 'direct-3210' ? value.ingress : null;
+  if (!executionPlane && !profile && !runtimeId && port === null && !ingress) return null;
+  return {
+    execution_plane: executionPlane,
+    profile,
+    listen_port: port,
+    runtime_id: runtimeId,
+    ...(ingress ? { ingress } : {}),
+  };
+}
+
+/**
+ * Build the machine-first Result Contract for a workflow.
+ *
+ * Deliberately excluded: worker prose, raw provider payloads and candidate
+ * patch text. The envelope contains enough evidence for orchestration while
+ * artifact inspection remains an explicit follow-up operation.
+ */
+export function buildEvidenceEnvelope(view = {}) {
+  const outcome = view.outcome ?? {};
+  const candidate = view.candidate ?? {};
+  const review = view.review ?? null;
+  const errorMessage = boundedText(view.error, 1000);
+  const changedFiles = boundedStrings(changedFilesFromView(view), { count: 120, length: 500 });
+  const status = evidenceStatus(view);
+  const reviewOnly = view.role === 'reviewer' && view.outcome == null;
+  const selectionAttempts = Array.isArray(view.child_attempts) && view.child_attempts.length > 0
+    ? view.child_attempts
+    : (view.selection_trace || view.provider || view.model ? [view] : []);
+  return {
+    schema_version: JOB_CONTRACT_SCHEMA_VERSION,
+    job_id: view.id ?? null,
+    client_job_id: view.client_job_id ?? null,
+    role: view.role ?? null,
+    status,
+    summary: {
+      phase: view.phase ?? null,
+      task_status: outcome.task_status ?? (reviewOnly && status === 'PASS' ? 'success' : null),
+      execution_status: outcome.execution_status ?? (reviewOnly && review?.status === 'done' ? 'completed' : null),
+      tests_status: outcome.tests_status ?? null,
+      delivery_complete: reviewOnly ? review?.delivery_complete === true : outcome.delivery?.complete === true,
+      review_verdict: review?.verdict ?? null,
+    },
+    selection_trace: compactSelectionTrace(selectionAttempts),
+    execution_context: boundedExecutionContext(view.execution_context ?? selectionAttempts[0]?.execution_context),
+    changed_files: changedFiles,
+    changes: boundedStrings(outcome.changes),
+    tests: boundedTests(outcome.tests),
+    risks: boundedStrings(reviewOnly ? review?.risks : outcome.risks),
+    unverified: boundedStrings(outcome.unverified),
+    review: review ? {
+      verdict: review.verdict ?? null,
+      status: review.status ?? null,
+      findings: boundedStrings(review.findings),
+      evidence: boundedStrings(review.evidence),
+      risks: boundedStrings(review.risks),
+      delivery_complete: review.delivery_complete === true,
+      mutated_candidate: review.mutated_candidate === true,
+    } : null,
+    artifacts: {
+      candidate_available: view.candidate_available === true || changedFiles.length > 0,
+      candidate_fingerprint: candidate.fingerprint ?? null,
+      base_revision: candidate.base_revision ?? view.base_revision ?? null,
+      workspace_retained: view.workspace_retained === true,
+      candidate_capture_failed: view.candidate_capture_failed === true,
+    },
+    errors: errorMessage || view.error_code ? [{ code: view.error_code ?? null, message: errorMessage }] : [],
+  };
+}
+
+/** Project a rich internal workflow view onto compact or explicit full detail. */
+export function projectWorkflowView(view, { detail = 'compact', afterSequence = 0 } = {}) {
+  if (!view || typeof view !== 'object') return view;
+  const evidence = buildEvidenceEnvelope(view);
+  const allCanonical = Array.isArray(view.canonical_events) ? view.canonical_events : [];
+  const cursor = allCanonical.at(-1)?.sequence ?? view.event_cursor ?? 0;
+  const canonicalEvents = allCanonical.filter((event) => Number(event?.sequence) > afterSequence);
+  const eventProjection = {
+    canonical_events: canonicalEvents,
+    event_cursor: cursor,
+    events_truncated_before_cursor: afterSequence > 0 && canonicalEvents.length > 0
+      ? canonicalEvents[0].sequence !== afterSequence + 1
+      : false,
+  };
+  if (detail === 'full') return { ...view, ...eventProjection, detail: 'full', evidence };
+
+  const {
+    candidate: _candidate,
+    outcome: _outcome,
+    review: _review,
+    events: _legacyEvents,
+    child_attempts: _childAttempts,
+    selection_trace: _rawSelectionTrace,
+    selection_source: _rawSelectionSource,
+    result: _rawResult,
+    workspace_diff: _workspaceDiff,
+    reasonDetail: _reasonDetail,
+    ...safe
+  } = view;
+  return {
+    ...safe,
+    ...eventProjection,
+    error: boundedText(view.error, 1000),
+    cleanup_warning: boundedText(view.cleanup_warning, 1000),
+    detail: 'compact',
+    evidence,
+  };
+}

package/src/local-request-guard.mjs

@@ -1,60 +1,60 @@
-// Shared local-request trust primitives for the two loopback surfaces:
-// the isolated 3210 hub API (src/hub/index.mjs) and the 3080→3210
-// official-web bridge (src/official-web-bridge.mjs). One implementation keeps
-// the two guards from drifting apart again.
-//
-// Trust model (see docs/ui-surfaces.md): both surfaces are loopback-only and
-// have no bearer token by design — every process running as the local user is
-// inside the trust boundary. The guards exist to keep off-machine browsers,
-// DNS-rebinding pages, and cross-machine proxies out, not to authenticate
-// local users. `localRequestCore` proves the peer is this machine (loopback
-// socket, local Host header, browser fetch-metadata pass); each surface then
-// layers its own Origin policy on top — the hub accepts any loopback origin
-// because the 3080 panel calls it cross-port, while the bridge requires an
-// exact authority match because it only serves its own same-origin client.
-
-function isIpv4Loopback(a) { return /^127(\.\d{1,3}){3}$/.test(a); }
-
-export function isLoopbackAddress(address) {
-  if (!address) return false;
-  const n = address.toLowerCase().split('%', 1)[0];
-  if (n === '::1' || isIpv4Loopback(n)) return true;
-  if (!n.startsWith('::ffff:')) return false;
-  return isIpv4Loopback(n.slice(7));
-}
-
-export function isLocalHostname(hostname) {
-  return hostname === 'localhost' || hostname === '::1' || hostname === '[::1]' || isIpv4Loopback(hostname);
-}
-
-/**
- * Core of both guards: loopback peer, loopback Host header, and (when the
- * client is a browser) a same-origin/none fetch-metadata request. Returns
- * false for anything that cannot be proven local.
- */
-export function localRequestCore(req) {
-  if (!isLoopbackAddress(req?.socket?.remoteAddress)) return false;
-  const host = typeof req?.headers?.host === 'string' ? req.headers.host.trim().toLowerCase() : '';
-  if (!host) return false;
-  let authority;
-  try { authority = new URL(`http://${host}`); } catch { return false; }
-  if (!isLocalHostname(authority.hostname.toLowerCase())) return false;
-  const fetchSite = String(req?.headers?.['sec-fetch-site'] ?? '').toLowerCase();
-  if (fetchSite && fetchSite !== 'same-origin' && fetchSite !== 'none') return false;
-  return true;
-}
-
-/** Hub Origin policy: an Origin, when present, must name a loopback host. */
-export function originLoopback(originHeader) {
-  if (typeof originHeader !== 'string') return false;
-  let parsed;
-  try { parsed = new URL(originHeader); } catch { return false; }
-  return isLocalHostname(parsed.hostname.toLowerCase());
-}
-
-/** Bridge Origin policy: the Origin authority must equal the request authority. */
-export function originAuthorityMatches(originHeader, host) {
-  if (!originLoopback(originHeader)) return false;
-  const parsed = new URL(originHeader);
-  return parsed.host.toLowerCase() === String(host).trim().toLowerCase();
-}
+// Shared local-request trust primitives for the two loopback surfaces:
+// the isolated 3210 hub API (src/hub/index.mjs) and the 3080→3210
+// official-web bridge (src/official-web-bridge.mjs). One implementation keeps
+// the two guards from drifting apart again.
+//
+// Trust model (see docs/ui-surfaces.md): both surfaces are loopback-only and
+// have no bearer token by design — every process running as the local user is
+// inside the trust boundary. The guards exist to keep off-machine browsers,
+// DNS-rebinding pages, and cross-machine proxies out, not to authenticate
+// local users. `localRequestCore` proves the peer is this machine (loopback
+// socket, local Host header, browser fetch-metadata pass); each surface then
+// layers its own Origin policy on top — the hub accepts any loopback origin
+// because the 3080 panel calls it cross-port, while the bridge requires an
+// exact authority match because it only serves its own same-origin client.
+
+function isIpv4Loopback(a) { return /^127(\.\d{1,3}){3}$/.test(a); }
+
+export function isLoopbackAddress(address) {
+  if (!address) return false;
+  const n = address.toLowerCase().split('%', 1)[0];
+  if (n === '::1' || isIpv4Loopback(n)) return true;
+  if (!n.startsWith('::ffff:')) return false;
+  return isIpv4Loopback(n.slice(7));
+}
+
+export function isLocalHostname(hostname) {
+  return hostname === 'localhost' || hostname === '::1' || hostname === '[::1]' || isIpv4Loopback(hostname);
+}
+
+/**
+ * Core of both guards: loopback peer, loopback Host header, and (when the
+ * client is a browser) a same-origin/none fetch-metadata request. Returns
+ * false for anything that cannot be proven local.
+ */
+export function localRequestCore(req) {
+  if (!isLoopbackAddress(req?.socket?.remoteAddress)) return false;
+  const host = typeof req?.headers?.host === 'string' ? req.headers.host.trim().toLowerCase() : '';
+  if (!host) return false;
+  let authority;
+  try { authority = new URL(`http://${host}`); } catch { return false; }
+  if (!isLocalHostname(authority.hostname.toLowerCase())) return false;
+  const fetchSite = String(req?.headers?.['sec-fetch-site'] ?? '').toLowerCase();
+  if (fetchSite && fetchSite !== 'same-origin' && fetchSite !== 'none') return false;
+  return true;
+}
+
+/** Hub Origin policy: an Origin, when present, must name a loopback host. */
+export function originLoopback(originHeader) {
+  if (typeof originHeader !== 'string') return false;
+  let parsed;
+  try { parsed = new URL(originHeader); } catch { return false; }
+  return isLocalHostname(parsed.hostname.toLowerCase());
+}
+
+/** Bridge Origin policy: the Origin authority must equal the request authority. */
+export function originAuthorityMatches(originHeader, host) {
+  if (!originLoopback(originHeader)) return false;
+  const parsed = new URL(originHeader);
+  return parsed.host.toLowerCase() === String(host).trim().toLowerCase();
+}