Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

test(open-knowledge): loopback bind-discipline scans, complementing #1812 (#1784)

Nick Gomez97b72b376dac
diff --git a/packages/app/tests/integration/advisory-warnings.test.ts b/packages/app/tests/integration/advisory-warnings.test.ts
index b1c76ef9c..40d5a028c 100644
--- a/packages/app/tests/integration/advisory-warnings.test.ts
+++ b/packages/app/tests/integration/advisory-warnings.test.ts
@@ -24,7 +24,7 @@ async function writeMd(
docName: string,
position: 'append' | 'prepend' | 'replace' = 'replace',
): Promise<{ status: number; body: WriteResponse }> {
- const res = await fetch(`http://localhost:${server.port}/api/agent-write-md`, {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ markdown, position, docName }),
@@ -37,7 +37,7 @@ async function patchDoc(
find: string,
replace: string,
): Promise<{ status: number; body: WriteResponse }> {
- const res = await fetch(`http://localhost:${server.port}/api/agent-patch`, {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/agent-patch`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ docName, find, replace }),
@@ -116,7 +116,7 @@ describe('advisory warnings on POST /api/frontmatter-patch', () => {
'---\ntitle: v1\n---\n\n# Doc\n\nbody-v2-native\n',
'utf-8',
);
- const res = await fetch(`http://localhost:${server.port}/api/frontmatter-patch`, {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/frontmatter-patch`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ docName, patch: { status: 'draft' } }),
diff --git a/packages/app/tests/integration/idle-shutdown-multi-client.test.ts b/packages/app/tests/integration/idle-shutdown-multi-client.test.ts
index 06946c963..a552641a6 100644
--- a/packages/app/tests/integration/idle-shutdown-multi-client.test.ts
+++ b/packages/app/tests/integration/idle-shutdown-multi-client.test.ts
@@ -29,6 +29,7 @@ beforeAll(async () => {
writeFileSync(join(okDir, 'config.yml'), '', 'utf-8');
writeFileSync(join(okDir, '.gitignore'), '', 'utf-8');
booted = await bootServer({
+ host: '127.0.0.1',
config: ConfigSchema.parse({}),
contentDir,
port: 0,
diff --git a/packages/app/tests/integration/loopback-bind-discipline.test.ts b/packages/app/tests/integration/loopback-bind-discipline.test.ts
new file mode 100644
index 000000000..fd55a9ce1
--- /dev/null
+++ b/packages/app/tests/integration/loopback-bind-discipline.test.ts
@@ -0,0 +1,176 @@
+import { describe, expect, test } from 'bun:test';
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, '..', '..');
+const SCAN_ROOTS = [__dirname, join(PACKAGE_ROOT, 'tests', 'stress')];
+
+const SELF_BASENAME = basename(fileURLToPath(import.meta.url));
+
+interface FileLines {
+ path: string;
+ lines: string[];
+}
+
+function listScannedFiles(): FileLines[] {
+ const out: FileLines[] = [];
+ function walk(dir: string) {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const abs = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ walk(abs);
+ continue;
+ }
+ if (!entry.isFile() || !entry.name.endsWith('.ts')) continue;
+ if (entry.name === SELF_BASENAME) continue;
+ out.push({
+ path: relative(PACKAGE_ROOT, abs),
+ lines: readFileSync(abs, 'utf-8').split('\n'),
+ });
+ }
+ }
+ for (const root of SCAN_ROOTS) walk(root);
+ return out;
+}
+
+function isCommentOnlyLine(line: string): boolean {
+ const trimmed = line.trim();
+ return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');
+}
+
+const LOOPBACK_HOST_LITERAL = /['"](?:127\.0\.0\.1|::1)['"]/;
+
+export function findNonLoopbackListenCalls(lines: string[]): Array<{ line: number; text: string }> {
+ const violations: Array<{ line: number; text: string }> = [];
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i] ?? '';
+ if (isCommentOnlyLine(line)) continue;
+ const idx = line.indexOf('.listen(');
+ if (idx === -1) continue;
+ let window = line.slice(idx);
+ for (let j = i + 1; j <= i + 3 && !window.includes(')') && j < lines.length; j++) {
+ window += `\n${lines[j] ?? ''}`;
+ }
+ const paren = window.indexOf(')');
+ if (paren !== -1) window = window.slice(0, paren + 1);
+ if (!LOOPBACK_HOST_LITERAL.test(window)) {
+ violations.push({ line: i + 1, text: line.trim() });
+ }
+ }
+ return violations;
+}
+
+const AMBIGUOUS_LOCALHOST_DIAL = /\b(?:https?|wss?):\/\/localhost:\$\{/;
+
+export function findAmbiguousLocalhostDials(
+ lines: string[],
+): Array<{ line: number; text: string }> {
+ const violations: Array<{ line: number; text: string }> = [];
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i] ?? '';
+ if (isCommentOnlyLine(line)) continue;
+ if (AMBIGUOUS_LOCALHOST_DIAL.test(line)) {
+ violations.push({ line: i + 1, text: line.trim() });
+ }
+ }
+ return violations;
+}
+
+describe('loopback bind discipline (app test sources)', () => {
+ const files = listScannedFiles();
+
+ test('there are test files to scan (sanity)', () => {
+ expect(files.length).toBeGreaterThan(0);
+ expect(files.some((f) => f.path.endsWith('integration/test-harness.ts'))).toBe(true);
+ expect(files.some((f) => f.path.endsWith('_helpers/server-process.ts'))).toBe(true);
+ expect(files.some((f) => f.path.endsWith('.e2e.ts'))).toBe(true);
+ });
+
+ test('every .listen( call binds an explicit loopback host literal', () => {
+ const violations: string[] = [];
+ for (const file of files) {
+ for (const v of findNonLoopbackListenCalls(file.lines)) {
+ violations.push(` ${file.path}:${v.line} ${v.text}`);
+ }
+ }
+ if (violations.length > 0) {
+ throw new Error(
+ `Hostless rig bind found — a bare listen(0) binds the IPv6 wildcard '::', whose loopback-specific ` +
+ `port slots stay silently bindable by foreign processes; their listeners then intercept this rig's ` +
+ `localhost dials (the rotating integration-suite flake). Bind a loopback-specific host ` +
+ `(e.g. listen(0, '127.0.0.1', cb)) and dial the literal from server.address():\n${violations.join('\n')}`,
+ );
+ }
+ });
+
+ test('no interpolated-port localhost dial URLs', () => {
+ const violations: string[] = [];
+ for (const file of files) {
+ for (const v of findAmbiguousLocalhostDials(file.lines)) {
+ violations.push(` ${file.path}:${v.line} ${v.text}`);
+ }
+ }
+ if (violations.length > 0) {
+ throw new Error(
+ `Ambiguous-name rig dial found — 'localhost' resolves '::1'-first, exactly the loopback-specific slot ` +
+ `a foreign process can hold while the rig sits on a wildcard (or single-family) bind. Dial the ` +
+ `literal address the rig actually bound (a harness-advertised base URL, or ` +
+ `http://127.0.0.1:\${port}):\n${violations.join('\n')}`,
+ );
+ }
+ });
+
+ test('listen predicate fires on planted violations and not on adjacent negatives', () => {
+ expect(findNonLoopbackListenCalls([' s.listen(0, () => {']).length).toBe(1);
+ expect(
+ findNonLoopbackListenCalls([' httpServer.listen(port, () => resolve());']).length,
+ ).toBe(1);
+
+ expect(findNonLoopbackListenCalls([" server.listen(0, '127.0.0.1', resolve);"]).length).toBe(
+ 0,
+ );
+ expect(findNonLoopbackListenCalls([" s.listen(port, '::1', cb);"]).length).toBe(0);
+
+ expect(
+ findNonLoopbackListenCalls([' server.listen(', ' 0,', " '127.0.0.1',", ' cb)'])
+ .length,
+ ).toBe(0);
+
+ expect(findNonLoopbackListenCalls([' // before httpServer.listen() resolves']).length).toBe(0);
+ expect(
+ findNonLoopbackListenCalls([' * boot scan runs BEFORE httpServer.listen().']).length,
+ ).toBe(0);
+
+ expect(findNonLoopbackListenCalls([' s.listen(port, host, cb);']).length).toBe(1);
+
+ expect(findNonLoopbackListenCalls([" s.listen(0, '0.0.0.0', cb);"]).length).toBe(1);
+ });
+
+ test('dial predicate fires on planted violations and not on adjacent negatives', () => {
+ expect(
+ findAmbiguousLocalhostDials([
+ ` const res = await fetch(\`http://localhost:\${server.port}/api/documents\`);`,
+ ]).length,
+ ).toBe(1);
+ expect(
+ findAmbiguousLocalhostDials([` url: \`ws://localhost:\${port}/collab\`,`]).length,
+ ).toBe(1);
+
+ expect(
+ findAmbiguousLocalhostDials([` const res = await fetch(\`http://127.0.0.1:\${port}/x\`);`])
+ .length,
+ ).toBe(0);
+
+ expect(
+ findAmbiguousLocalhostDials([" expect(url).toBe('ws://localhost:7777/collab');"]).length,
+ ).toBe(0);
+
+ expect(findAmbiguousLocalhostDials([` // dials http://localhost:\${port} today`]).length).toBe(
+ 0,
+ );
+
+ expect(findAmbiguousLocalhostDials([" host: 'localhost:5173',"]).length).toBe(0);
+ });
+});
diff --git a/packages/app/tests/integration/loopback-exclusivity.test.ts b/packages/app/tests/integration/loopback-exclusivity.test.ts
new file mode 100644
index 000000000..1ad9f7a80
--- /dev/null
+++ b/packages/app/tests/integration/loopback-exclusivity.test.ts
@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { createServer } from 'node:http';
+
+import { createTestServer } from './test-harness';
+
+interface ForeignMarker {
+ host: string;
+ close: () => Promise<void>;
+}
+
+function tryBindForeignMarker(
+ host: '127.0.0.1' | '::1',
+ port: number,
+ markerToken: string,
+): Promise<ForeignMarker | 'rig-owned' | 'family-unavailable'> {
+ return new Promise((resolve, reject) => {
+ const s = createServer((_req, res) => {
+ res.writeHead(200, {
+ 'content-type': 'application/json',
+ 'x-foreign-marker': markerToken,
+ });
+ res.end(JSON.stringify({ foreignMarker: markerToken, answeredOn: host }));
+ });
+ s.on('error', (err: NodeJS.ErrnoException) => {
+ if (err.code === 'EADDRINUSE') resolve('rig-owned');
+ else if (err.code === 'EADDRNOTAVAIL' || err.code === 'EAFNOSUPPORT')
+ resolve('family-unavailable');
+ else reject(err);
+ });
+ s.listen(port, host === '::1' ? '::1' : '127.0.0.1', () => {
+ resolve({
+ host,
+ close: () => new Promise<void>((r) => s.close(() => r())),
+ });
+ });
+ });
+}
+
+function dialedLoopbackAddresses(baseUrl: string): Array<'127.0.0.1' | '::1'> {
+ const hostname = new URL(baseUrl).hostname;
+ if (hostname === 'localhost') return ['127.0.0.1', '::1'];
+ if (hostname === '127.0.0.1') return ['127.0.0.1'];
+ if (hostname === '::1' || hostname === '[::1]') return ['::1'];
+ throw new Error(`harness advertises a non-loopback dial host: ${hostname}`);
+}
+
+describe('test-harness loopback exclusivity', () => {
+ const cleanups: Array<() => Promise<void>> = [];
+ afterEach(async () => {
+ const errors: unknown[] = [];
+ while (cleanups.length > 0) {
+ const fn = cleanups.pop();
+ if (!fn) continue;
+ try {
+ await fn();
+ } catch (err) {
+ errors.push(err);
+ }
+ }
+ if (errors.length > 0) throw new AggregateError(errors, 'loopback-exclusivity cleanup failed');
+ });
+
+ test('consumer dial reaches the harness server even when a foreign loopback-specific listener squats its port', async () => {
+ const server = await createTestServer();
+ cleanups.push(server.cleanup);
+
+ const markerToken = `foreign-${crypto.randomUUID()}`;
+ for (const host of ['127.0.0.1', '::1'] as const) {
+ const marker = await tryBindForeignMarker(host, server.port, markerToken);
+ if (typeof marker === 'object') cleanups.push(marker.close);
+ }
+
+ const res = await fetch(`${server.baseUrl}/api/documents`);
+ const body = (await res.json()) as { documents?: unknown };
+
+ expect(res.headers.get('x-foreign-marker')).toBeNull();
+ expect(res.status).toBe(200);
+ expect(Array.isArray(body.documents)).toBe(true);
+ });
+
+ test('harness server exclusively owns every loopback address its consumer dial URL can resolve to', async () => {
+ const server = await createTestServer();
+ cleanups.push(server.cleanup);
+
+ const squattable: string[] = [];
+ for (const host of dialedLoopbackAddresses(server.baseUrl)) {
+ const marker = await tryBindForeignMarker(host, server.port, 'exclusivity-probe');
+ if (marker === 'family-unavailable') continue;
+ if (typeof marker === 'object') {
+ squattable.push(host);
+ cleanups.push(marker.close);
+ }
+ }
+
+ expect(squattable).toEqual([]);
+ });
+});
diff --git a/packages/app/tests/integration/stale-idb-lineage-record-absent-doors.test.ts b/packages/app/tests/integration/stale-idb-lineage-record-absent-doors.test.ts
index 2a9baaace..b94e87edf 100644
--- a/packages/app/tests/integration/stale-idb-lineage-record-absent-doors.test.ts
+++ b/packages/app/tests/integration/stale-idb-lineage-record-absent-doors.test.ts
@@ -128,7 +128,7 @@ async function stageStaleRowsAndReseed(opts: {
storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
}): Promise<void> {
const { server, docName, filePath, storage } = opts;
- const poolA = new ProviderPool(3, `ws://localhost:${server.port}/collab`, { storage });
+ const poolA = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, { storage });
const serverInstanceId = await seedPoolServerInstanceId(server, poolA);
poolA.open(docName);
poolA.setActive(docName);
@@ -193,7 +193,7 @@ describe('client-persisted state meets a re-seeded doc lineage (boot-window fres
expect(envelopeRaw).not.toBeNull();
expect(envelopeRaw as string).toContain(docName);
- const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {
+ const poolB = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {
storage: sharedStorage,
});
cleanups.push(() => poolB.dispose());
@@ -233,7 +233,7 @@ describe('client-persisted state meets a re-seeded doc lineage (record-absent pr
await stageStaleRowsAndReseed({ server, docName, filePath, storage: storageA });
const { stub: emptyStorage } = makeStubStorage();
- const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {
+ const poolB = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {
storage: emptyStorage,
});
cleanups.push(() => poolB.dispose());
@@ -269,7 +269,7 @@ describe('refusing dead-lineage state is observable (boot-window fresh-pool door
const capture = captureLineageMismatchWarns();
cleanups.push(capture.restore);
- const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {
+ const poolB = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {
storage: sharedStorage,
});
cleanups.push(() => poolB.dispose());
@@ -310,7 +310,7 @@ describe('refusing dead-lineage state is observable (record-absent profile door)
cleanups.push(capture.restore);
const { stub: emptyStorage } = makeStubStorage();
- const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {
+ const poolB = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {
storage: emptyStorage,
});
cleanups.push(() => poolB.dispose());
diff --git a/packages/app/tests/integration/test-harness.ts b/packages/app/tests/integration/test-harness.ts
index 5457ff009..6467b225b 100644
--- a/packages/app/tests/integration/test-harness.ts
+++ b/packages/app/tests/integration/test-harness.ts
@@ -63,6 +63,8 @@ async function getFreePort(): Promise<number> {
export interface TestServer {
port: number;
+ baseUrl: string;
+ wsUrl: string;
contentDir: string;
instance: ServerInstance;
cleanup: () => Promise<void>;
@@ -157,12 +159,22 @@ export async function createTestServer(options: CreateTestServerOptions = {}): P
keepaliveGraceMs: options.keepaliveGraceMs,
});
- await new Promise<void>((resolve) => {
- httpServer.listen(port, '127.0.0.1', () => resolve());
+ await new Promise<void>((resolve, reject) => {
+ const onErr = (err: Error): void => {
+ httpServer.off('error', onErr);
+ reject(err);
+ };
+ httpServer.once('error', onErr);
+ httpServer.listen(port, '127.0.0.1', () => {
+ httpServer.off('error', onErr);
+ resolve();
+ });
});
return {
port,
+ baseUrl: `http://127.0.0.1:${port}`,
+ wsUrl: `ws://127.0.0.1:${port}`,
contentDir,
instance: srv,
cleanup: async () => {
@@ -890,7 +902,7 @@ export async function waitForPortFree(port: number, timeoutMs = 2500): Promise<v
lastErr = err;
resolve(false);
});
- probe.listen(port, () => {
+ probe.listen(port, '127.0.0.1', () => {
probe.close(() => resolve(true));
});
});
@@ -964,7 +976,7 @@ export async function createRestartableServer(
reject(err);
};
httpServer.once('error', onErr);
- httpServer.listen(port, () => {
+ httpServer.listen(port, '127.0.0.1', () => {
httpServer.off('error', onErr);
resolve();
});
diff --git a/packages/app/tests/integration/worktree-boot.test.ts b/packages/app/tests/integration/worktree-boot.test.ts
index d679a2079..f349be6e5 100644
--- a/packages/app/tests/integration/worktree-boot.test.ts
+++ b/packages/app/tests/integration/worktree-boot.test.ts
@@ -28,6 +28,7 @@ describe('bootServer in a linked git worktree (FR2)', () => {
expect(existsSync(expectedShadowHead)).toBe(false);
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: handle.worktreePath,
port: 0,
@@ -53,6 +54,7 @@ describe('bootServer pre-listen check in a linked worktree (FR3)', () => {
let caught: unknown;
try {
await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: handle.worktreePath,
port: 0,
@@ -79,6 +81,7 @@ describe('bootServer pre-listen check in a linked worktree (FR3)', () => {
let caught: unknown;
try {
await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: handle.worktreePath,
port: 0,
@@ -113,6 +116,7 @@ describe('bootServer pre-listen check in a linked worktree (FR3)', () => {
let booted: Awaited<ReturnType<typeof bootServer>> | null = null;
try {
booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: handle.worktreePath,
port: 0,
@@ -159,6 +163,7 @@ describe('bootServer ok.boot span attributes against a real linked worktree', ()
handle = createLinkedWorktree({ seedOkScaffold: true });
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: handle.worktreePath,
port: 0,
@@ -215,6 +220,7 @@ describe('bootServer pre-listen check on main worktree (FR3)', () => {
let caught: unknown;
try {
await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
@@ -243,6 +249,7 @@ describe('bootServer pre-listen check on main worktree (FR3)', () => {
let caught: unknown;
try {
await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
diff --git a/packages/app/tests/integration/worktree-cleanup-and-stale-pointer.test.ts b/packages/app/tests/integration/worktree-cleanup-and-stale-pointer.test.ts
index e6f4aebc0..bdbfce831 100644
--- a/packages/app/tests/integration/worktree-cleanup-and-stale-pointer.test.ts
+++ b/packages/app/tests/integration/worktree-cleanup-and-stale-pointer.test.ts
@@ -26,6 +26,7 @@ describe('git worktree remove cleans up the per-worktree shadow (FR6)', () => {
const shadowHead = resolve(adminDir, 'ok/HEAD');
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: handle.worktreePath,
port: 0,
@@ -67,6 +68,7 @@ describe('MalformedGitPointerError at boot when .git pointer is stale (FR7)', ()
let caught: unknown;
try {
await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: projectRoot,
port: 0,
@@ -90,6 +92,7 @@ describe('MalformedGitPointerError at boot when .git pointer is stale (FR7)', ()
handle = createLinkedWorktree({ seedOkScaffold: true });
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: handle.worktreePath,
port: 0,
@@ -119,6 +122,7 @@ describe('MalformedGitPointerError at boot when .git pointer is stale (FR7)', ()
let firstAttemptError: unknown;
try {
await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: projectRoot,
port: 0,
@@ -136,6 +140,7 @@ describe('MalformedGitPointerError at boot when .git pointer is stale (FR7)', ()
mkdirSync(resolve(projectRoot, '.git'), { recursive: true });
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: projectRoot,
port: 0,
diff --git a/packages/app/tests/integration/worktree-concurrent.test.ts b/packages/app/tests/integration/worktree-concurrent.test.ts
index 43f72d704..39c8f3269 100644
--- a/packages/app/tests/integration/worktree-concurrent.test.ts
+++ b/packages/app/tests/integration/worktree-concurrent.test.ts
@@ -27,6 +27,7 @@ describe('Two linked worktrees boot in parallel with isolated state (D13)', () =
const [bootedA, bootedB] = await Promise.all([
bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: a.worktreePath,
port: 0,
@@ -36,6 +37,7 @@ describe('Two linked worktrees boot in parallel with isolated state (D13)', () =
attachUiSibling: false,
}),
bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: b.worktreePath,
port: 0,
diff --git a/packages/app/tests/integration/worktree-init.test.ts b/packages/app/tests/integration/worktree-init.test.ts
index c9ed87327..19857798b 100644
--- a/packages/app/tests/integration/worktree-init.test.ts
+++ b/packages/app/tests/integration/worktree-init.test.ts
@@ -49,6 +49,7 @@ describe('initContent in a linked worktree (FR4 / D7)', () => {
initContent(handle.worktreePath);
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: handle.worktreePath,
port: 0,
diff --git a/packages/app/tests/stress/_helpers/fixtures.ts b/packages/app/tests/stress/_helpers/fixtures.ts
index 5630f1182..0ae745b13 100644
--- a/packages/app/tests/stress/_helpers/fixtures.ts
+++ b/packages/app/tests/stress/_helpers/fixtures.ts
@@ -96,11 +96,11 @@ export const test = base.extend<TestFixtures, WorkerFixtures>({
const contentDir = mkdtempSync(join(tmpdir(), `ok-w${workerInfo.workerIndex}-`));
const viteCacheDir = prepareViteCacheDir(`w${workerInfo.workerIndex}`);
seedRequiredFixtureFiles(contentDir);
- const baseURL = `http://localhost:${port}`;
+ const baseURL = `http://127.0.0.1:${port}`;
const serverLog = openServerLog(`w${workerInfo.workerIndex}`);
- const proc = spawn('bun', ['run', '--silent', 'dev'], {
+ const proc = spawn('bun', ['run', '--silent', 'dev', '--host', '127.0.0.1'], {
cwd: APP_PACKAGE_ROOT,
env: {
...process.env,
diff --git a/packages/app/tests/stress/_helpers/global-warm-cache.ts b/packages/app/tests/stress/_helpers/global-warm-cache.ts
index 7d531e2b1..f8722f1bb 100644
--- a/packages/app/tests/stress/_helpers/global-warm-cache.ts
+++ b/packages/app/tests/stress/_helpers/global-warm-cache.ts
@@ -68,7 +68,7 @@ async function buildSeedOnce(key: string): Promise<void> {
mkdirSync(join(APP_PACKAGE_ROOT, 'node_modules'), { recursive: true });
const buildDir = mkdtempSync(join(APP_PACKAGE_ROOT, 'node_modules', '.vite-e2e-seed-building-'));
const log = openServerLog('warm-cache');
- const proc = spawn('bun', ['run', '--silent', 'dev'], {
+ const proc = spawn('bun', ['run', '--silent', 'dev', '--host', '127.0.0.1'], {
cwd: APP_PACKAGE_ROOT,
env: {
...process.env,
@@ -84,7 +84,7 @@ async function buildSeedOnce(key: string): Promise<void> {
});
let succeeded = false;
try {
- await waitForHttpReady(`http://localhost:${port}`, 60_000);
+ await waitForHttpReady(`http://127.0.0.1:${port}`, 60_000);
const depsDir = join(buildDir, 'deps');
const metaPath = join(depsDir, '_metadata.json');
const deadline = Date.now() + OPTIMIZER_SETTLE_BUDGET_MS;
diff --git a/packages/app/tests/stress/_helpers/server-process.ts b/packages/app/tests/stress/_helpers/server-process.ts
index 54aa38f09..bd5192d45 100644
--- a/packages/app/tests/stress/_helpers/server-process.ts
+++ b/packages/app/tests/stress/_helpers/server-process.ts
@@ -63,10 +63,14 @@ export function tailServerLog(log: ServerLog, lines = 40): string {
}
}
-export async function checkCollabSync(port: number, timeoutMs = 10_000): Promise<void> {
+export async function checkCollabSync(
+ port: number,
+ timeoutMs = 10_000,
+ loopbackHost: '127.0.0.1' | '::1' = '127.0.0.1',
+): Promise<void> {
const doc = new Y.Doc();
const provider = new HocuspocusProvider({
- url: `ws://localhost:${port}/collab`,
+ url: `ws://${loopbackHost === '::1' ? '[::1]' : '127.0.0.1'}:${port}/collab`,
name: SYSTEM_DOC_NAME,
document: doc,
connect: false,
@@ -92,11 +96,13 @@ export async function checkCollabSync(port: number, timeoutMs = 10_000): Promise
}
}
-export async function getFreePort(): Promise<number> {
+export async function getFreePort(
+ loopbackHost: '127.0.0.1' | '::1' = '127.0.0.1',
+): Promise<number> {
return new Promise((resolve, reject) => {
const s = createNetServer();
s.once('error', reject);
- s.listen(0, () => {
+ s.listen(0, loopbackHost === '::1' ? '::1' : '127.0.0.1', () => {
const port = (s.address() as AddressInfo).port;
s.close(() => resolve(port));
});
diff --git a/packages/app/tests/stress/create-then-rename-editable.e2e.ts b/packages/app/tests/stress/create-then-rename-editable.e2e.ts
index d125368a2..bcc911c1a 100644
--- a/packages/app/tests/stress/create-then-rename-editable.e2e.ts
+++ b/packages/app/tests/stress/create-then-rename-editable.e2e.ts
@@ -84,6 +84,6 @@ test.describe('create → inline-rename → click → type', () => {
const stuckWarmFallbackCount = await page.locator('.tiptap-editor[aria-hidden="true"]').count();
expect(stuckWarmFallbackCount).toBe(0);
- expect(workerServer.baseURL).toMatch(/^http:\/\/localhost:\d+$/);
+ expect(workerServer.baseURL).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
});
});
diff --git a/packages/app/tests/stress/file-tree-create.e2e.ts b/packages/app/tests/stress/file-tree-create.e2e.ts
index 013f863e9..758011ab2 100644
--- a/packages/app/tests/stress/file-tree-create.e2e.ts
+++ b/packages/app/tests/stress/file-tree-create.e2e.ts
@@ -179,7 +179,7 @@ async function installDelayedDesktopSessionBridge(
platform: 'darwin',
config: {
apiOrigin: baseURL,
- collabUrl: `ws://localhost:${port}/collab`,
+ collabUrl: `ws://127.0.0.1:${port}/collab`,
mode: 'editor',
projectName: 'session-restore-test',
projectPath: contentDir,
diff --git a/packages/app/tests/stress/init-load-byte-stable.e2e.ts b/packages/app/tests/stress/init-load-byte-stable.e2e.ts
index f17e1e8dd..4655190d3 100644
--- a/packages/app/tests/stress/init-load-byte-stable.e2e.ts
+++ b/packages/app/tests/stress/init-load-byte-stable.e2e.ts
@@ -39,7 +39,7 @@ interface OkFixture {
const test = base.extend<{ okFixture: OkFixture }>({
// biome-ignore lint/correctness/noEmptyPattern: Playwright requires an object-destructuring pattern for the fixtures arg; this fixture has no dependencies so the destructure is empty by design (matches the convention used by the `workerServer` fixture in `_helpers/fixtures.ts`).
okFixture: async ({}, use) => {
- const port = await getFreePort();
+ const port = await getFreePort('::1');
const contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-init-load-e2e-')));
for (const entry of CORPUS) {
@@ -52,10 +52,10 @@ const test = base.extend<{ okFixture: OkFixture }>({
installUserSkill: async () => 'skip-current',
});
- const baseURL = `http://localhost:${port}`;
+ const baseURL = `http://[::1]:${port}`;
const viteCacheDir = prepareViteCacheDir('init-load');
const serverLog = openServerLog('init-load');
- const proc = spawn('bun', ['run', '--silent', 'dev'], {
+ const proc = spawn('bun', ['run', '--silent', 'dev', '--host', '::1'], {
cwd: APP_PACKAGE_ROOT,
env: {
...process.env,
@@ -72,7 +72,7 @@ const test = base.extend<{ okFixture: OkFixture }>({
await Promise.race([
(async () => {
await waitForHttpReady(baseURL, 60_000);
- await checkCollabSync(port);
+ await checkCollabSync(port, 10_000, '::1');
})(),
new Promise<never>((_, reject) => {
proc.once('error', (err) => reject(err));
diff --git a/packages/app/tests/stress/rename-noext-probe.e2e.ts b/packages/app/tests/stress/rename-noext-probe.e2e.ts
index 2e3903bda..8338a3804 100644
--- a/packages/app/tests/stress/rename-noext-probe.e2e.ts
+++ b/packages/app/tests/stress/rename-noext-probe.e2e.ts
@@ -23,7 +23,7 @@ test.describe('PROBE: sidebar rename — no-extension typed', () => {
api,
workerServer,
}) => {
- const baseURL = `http://localhost:${workerServer.port}`;
+ const baseURL = `http://127.0.0.1:${workerServer.port}`;
const suffix = randomUUID().slice(0, 8);
const srcName = `probe-src-${suffix}`;
const dstName = `probe-dst-${suffix}`;
diff --git a/packages/app/tests/stress/single-file-ephemeral.e2e.ts b/packages/app/tests/stress/single-file-ephemeral.e2e.ts
index 0194df592..38ca715a4 100644
--- a/packages/app/tests/stress/single-file-ephemeral.e2e.ts
+++ b/packages/app/tests/stress/single-file-ephemeral.e2e.ts
@@ -45,7 +45,7 @@ interface EphemeralFixture {
const test = base.extend<{ ephemeral: EphemeralFixture }>({
// biome-ignore lint/correctness/noEmptyPattern: Playwright requires an object-destructuring pattern; this fixture has no dependencies.
ephemeral: async ({}, use) => {
- const port = await getFreePort();
+ const port = await getFreePort('::1');
const userDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-sf-e2e-')));
const notesDir = join(userDir, 'notes');
mkdirSync(notesDir, { recursive: true });
@@ -55,10 +55,10 @@ const test = base.extend<{ ephemeral: EphemeralFixture }>({
writeFileSync(join(notesDir, 'pic.png'), 'not-a-real-png', 'utf-8');
const projectDir = createEphemeralProjectDir(notesDir);
- const baseURL = `http://localhost:${port}`;
+ const baseURL = `http://[::1]:${port}`;
const viteCacheDir = prepareViteCacheDir('sf-ephemeral');
const serverLog = openServerLog('sf-ephemeral');
- const proc = spawn('bun', ['run', '--silent', 'dev'], {
+ const proc = spawn('bun', ['run', '--silent', 'dev', '--host', '::1'], {
cwd: APP_PACKAGE_ROOT,
env: {
...process.env,
@@ -77,7 +77,7 @@ const test = base.extend<{ ephemeral: EphemeralFixture }>({
await Promise.race([
(async () => {
await waitForHttpReady(baseURL, 60_000);
- await checkCollabSync(port);
+ await checkCollabSync(port, 10_000, '::1');
})(),
new Promise<never>((_, reject) => {
proc.once('error', (err) => reject(err));
diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.ts
index e3896ba94..2b7616c72 100644
--- a/packages/cli/src/commands/start.test.ts
+++ b/packages/cli/src/commands/start.test.ts
@@ -848,7 +848,7 @@ describe('bootStartServer (integration)', () => {
skipUiAutoSpawn: true,
});
- const ws = new WebSocket(`ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}`);
+ const ws = new WebSocket(`ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}`);
try {
await new Promise<void>((done, fail) => {
const onOpen = () => {
diff --git a/packages/cli/src/commands/ui-proxy.test.ts b/packages/cli/src/commands/ui-proxy.test.ts
index 94ccd0cd1..5f6ed5744 100644
--- a/packages/cli/src/commands/ui-proxy.test.ts
+++ b/packages/cli/src/commands/ui-proxy.test.ts
@@ -19,7 +19,7 @@ async function rawRequest(opts: {
return new Promise((done, fail) => {
const req = httpRequest(
{
- host: 'localhost',
+ host: '127.0.0.1',
port: opts.port,
path: opts.path,
method: opts.method ?? 'GET',
@@ -56,7 +56,7 @@ async function startUpstream(
await new Promise<void>((done, fail) => {
const onError = (err: Error) => fail(err);
server.once('error', onError);
- server.listen(0, 'localhost', () => {
+ server.listen(0, '127.0.0.1', () => {
server.off('error', onError);
done();
});
@@ -95,12 +95,12 @@ describe('startProxyServer', () => {
proxy = await startProxyServer({
listenPort: 0,
- host: 'localhost',
- upstreamHost: 'localhost',
+ host: '127.0.0.1',
+ upstreamHost: '127.0.0.1',
upstreamPort: upstream.port,
});
- const response = await fetch(`http://localhost:${proxy.port}/hello`);
+ const response = await fetch(`http://127.0.0.1:${proxy.port}/hello`);
expect(response.status).toBe(200);
expect(await response.text()).toBe('hello world');
expect(response.headers.get('content-type')).toContain('text/plain');
@@ -120,12 +120,12 @@ describe('startProxyServer', () => {
proxy = await startProxyServer({
listenPort: 0,
- host: 'localhost',
- upstreamHost: 'localhost',
+ host: '127.0.0.1',
+ upstreamHost: '127.0.0.1',
upstreamPort: upstream.port,
});
- const response = await fetch(`http://localhost:${proxy.port}/echo`, {
+ const response = await fetch(`http://127.0.0.1:${proxy.port}/echo`, {
method: 'POST',
body: payload,
headers: { 'Content-Type': 'text/plain' },
@@ -143,12 +143,12 @@ describe('startProxyServer', () => {
proxy = await startProxyServer({
listenPort: 0,
- host: 'localhost',
- upstreamHost: 'localhost',
+ host: '127.0.0.1',
+ upstreamHost: '127.0.0.1',
upstreamPort: upstream.port,
});
- const response = await fetch(`http://localhost:${proxy.port}/missing`);
+ const response = await fetch(`http://127.0.0.1:${proxy.port}/missing`);
expect(response.status).toBe(404);
expect(response.headers.get('x-custom')).toBe('not-found');
expect(await response.text()).toBe('nope');
@@ -163,12 +163,12 @@ describe('startProxyServer', () => {
proxy = await startProxyServer({
listenPort: 0,
- host: 'localhost',
- upstreamHost: 'localhost',
+ host: '127.0.0.1',
+ upstreamHost: '127.0.0.1',
upstreamPort: upstream.port,
});
- const response = await fetch(`http://localhost:${proxy.port}/head`, { method: 'HEAD' });
+ const response = await fetch(`http://127.0.0.1:${proxy.port}/head`, { method: 'HEAD' });
expect(response.status).toBe(200);
expect(response.headers.get('x-meta')).toBe('yes');
expect(await response.text()).toBe('');
@@ -182,12 +182,12 @@ describe('startProxyServer', () => {
proxy = await startProxyServer({
listenPort: 0,
- host: 'localhost',
- upstreamHost: 'localhost',
+ host: '127.0.0.1',
+ upstreamHost: '127.0.0.1',
upstreamPort: deadPort,
});
- const response = await fetch(`http://localhost:${proxy.port}/whatever`);
+ const response = await fetch(`http://127.0.0.1:${proxy.port}/whatever`);
expect(response.status).toBe(502);
expect(response.headers.get('content-type')).toBe('application/problem+json');
const body = (await response.json()) as { type: string; title: string; status: number };
@@ -199,15 +199,15 @@ describe('startProxyServer', () => {
upstream = await startUpstream((_req, res) => res.end('ok'));
proxy = await startProxyServer({
listenPort: 0,
- host: 'localhost',
- upstreamHost: 'localhost',
+ host: '127.0.0.1',
+ upstreamHost: '127.0.0.1',
upstreamPort: upstream.port,
});
const port = proxy.port;
await proxy.close();
proxy = null;
- await expect(fetch(`http://localhost:${port}/`)).rejects.toThrow();
+ await expect(fetch(`http://127.0.0.1:${port}/`)).rejects.toThrow();
});
test('rejects requests with non-loopback Host header (DNS-rebind defense)', async () => {
@@ -218,8 +218,8 @@ describe('startProxyServer', () => {
});
proxy = await startProxyServer({
listenPort: 0,
- host: 'localhost',
- upstreamHost: 'localhost',
+ host: '127.0.0.1',
+ upstreamHost: '127.0.0.1',
upstreamPort: upstream.port,
});
@@ -244,8 +244,8 @@ describe('startProxyServer', () => {
});
proxy = await startProxyServer({
listenPort: 0,
- host: 'localhost',
- upstreamHost: 'localhost',
+ host: '127.0.0.1',
+ upstreamHost: '127.0.0.1',
upstreamPort: upstream.port,
});
@@ -268,8 +268,8 @@ describe('startProxyServer', () => {
});
proxy = await startProxyServer({
listenPort: 0,
- host: 'localhost',
- upstreamHost: 'localhost',
+ host: '127.0.0.1',
+ upstreamHost: '127.0.0.1',
upstreamPort: upstream.port,
});
@@ -285,14 +285,14 @@ describe('startProxyServer', () => {
upstream = await startUpstream((_req, res) => res.end('ok'));
const pickerSrv = createHttpServer();
- await new Promise<void>((done) => pickerSrv.listen(0, 'localhost', () => done()));
+ await new Promise<void>((done) => pickerSrv.listen(0, '127.0.0.1', () => done()));
const requested = (pickerSrv.address() as { port: number }).port;
await new Promise<void>((done) => pickerSrv.close(() => done()));
proxy = await startProxyServer({
listenPort: requested,
- host: 'localhost',
- upstreamHost: 'localhost',
+ host: '127.0.0.1',
+ upstreamHost: '127.0.0.1',
upstreamPort: upstream.port,
});
expect(proxy.port).toBe(requested);
diff --git a/packages/cli/src/commands/ui.test.ts b/packages/cli/src/commands/ui.test.ts
index bd6e9b40c..5105a6bf9 100644
--- a/packages/cli/src/commands/ui.test.ts
+++ b/packages/cli/src/commands/ui.test.ts
@@ -98,7 +98,7 @@ function config() {
}
async function get(port: number, path: string) {
- const res = await fetch(`http://localhost:${port}${path}`);
+ const res = await fetch(`http://127.0.0.1:${port}${path}`);
const body = await res.text();
return { status: res.status, body, headers: res.headers };
}
@@ -126,7 +126,7 @@ async function rawRequest(opts: {
return new Promise((done, fail) => {
const req = httpRequest(
{
- host: 'localhost',
+ host: '127.0.0.1',
port: opts.port,
path: opts.path,
method: opts.method ?? 'GET',
@@ -157,6 +157,44 @@ async function rawRequest(opts: {
});
}
+type UpstreamSurrogate = { port: number; close: () => Promise<void> };
+
+async function startDualLoopbackUpstream(
+ handler: Parameters<typeof createHttpServer>[1],
+): Promise<UpstreamSurrogate> {
+ const v6 = createHttpServer(handler);
+ await new Promise<void>((done, fail) => {
+ v6.once('error', fail);
+ v6.listen(0, '::1', () => {
+ v6.off('error', fail);
+ done();
+ });
+ });
+ const port = (v6.address() as { port: number }).port;
+ const v4 = createHttpServer(handler);
+ try {
+ await new Promise<void>((done, fail) => {
+ v4.once('error', fail);
+ v4.listen(port, '127.0.0.1', () => {
+ v4.off('error', fail);
+ done();
+ });
+ });
+ } catch (err) {
+ await new Promise<void>((r) => v6.close(() => r()));
+ throw err;
+ }
+ return {
+ port,
+ close: async () => {
+ await Promise.all([
+ new Promise<void>((r) => v6.close(() => r())),
+ new Promise<void>((r) => v4.close(() => r())),
+ ]);
+ },
+ };
+}
+
describe('resolveRequestedPort', () => {
test('default is DEFAULT_UI_PORT with kernel-allocated fallback', () => {
expect(resolveRequestedPort(undefined, undefined)).toEqual({
@@ -198,7 +236,7 @@ describe('resolveRequestedPort', () => {
describe('startUiServer', () => {
test('binds requested port and writes ui.lock with resolved port', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
expect(handle.port).toBeGreaterThan(0);
const lockPath = resolve(lockDir, 'ui.lock');
@@ -281,7 +319,7 @@ describe('startUiServer', () => {
});
test('/api/config returns collabUrl=null when server.lock is absent', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { status, body, headers } = await get(handle.port, '/api/config');
expect(status).toBe(200);
expect(headers.get('content-type')).toContain('application/json');
@@ -294,11 +332,11 @@ describe('startUiServer', () => {
test('/api/config returns an armed paneTarget; DELETE consumes it', async () => {
armPaneTarget(lockDir, '#/specs/foo/SPEC');
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const first = JSON.parse((await get(handle.port, '/api/config')).body);
expect(first.paneTarget).toBe('#/specs/foo/SPEC');
- const del = await fetch(`http://localhost:${handle.port}/api/config`, { method: 'DELETE' });
+ const del = await fetch(`http://127.0.0.1:${handle.port}/api/config`, { method: 'DELETE' });
expect(del.status).toBe(204);
expect(readArmedPaneTarget(lockDir)).toBeNull();
@@ -308,15 +346,15 @@ describe('startUiServer', () => {
test('base-open GET / 302-redirects to an armed pane target and consumes it', async () => {
armPaneTarget(lockDir, '#/specs/foo/SPEC');
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
- const res = await fetch(`http://localhost:${handle.port}/`, { redirect: 'manual' });
+ const res = await fetch(`http://127.0.0.1:${handle.port}/`, { redirect: 'manual' });
expect(res.status).toBe(302);
expect(res.headers.get('location')).toBe('/#/specs/foo/SPEC');
expect(res.headers.get('cache-control')).toBe('no-store');
expect(readArmedPaneTarget(lockDir)).toBeNull();
- const follow = await fetch(`http://localhost:${handle.port}/`, { redirect: 'manual' });
+ const follow = await fetch(`http://127.0.0.1:${handle.port}/`, { redirect: 'manual' });
expect(follow.status).not.toBe(302);
});
@@ -326,10 +364,10 @@ describe('startUiServer', () => {
config: config(),
cwd: tmpDir,
port: 0,
- host: 'localhost',
+ host: '127.0.0.1',
assetDir: dist,
});
- const res = await fetch(`http://localhost:${handle.port}/`, { redirect: 'manual' });
+ const res = await fetch(`http://127.0.0.1:${handle.port}/`, { redirect: 'manual' });
expect(res.status).toBe(200);
expect(await res.text()).toContain('id="root"');
});
@@ -338,41 +376,41 @@ describe('startUiServer', () => {
acquireServerLock(lockDir, { port: 0, worktreeRoot: tmpDir });
updateServerLockPort(lockDir, 54321);
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { body } = await get(handle.port, '/api/config');
const parsed = JSON.parse(body);
- expect(parsed.collabUrl).toBe(`ws://localhost:${handle.port}/collab`);
+ expect(parsed.collabUrl).toBe(`ws://127.0.0.1:${handle.port}/collab`);
});
test('/api/config has no-store cache-control', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { headers } = await get(handle.port, '/api/config');
expect(headers.get('cache-control')).toBe('no-store');
});
test('HEAD /api/config returns 200 with no body', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
- const res = await fetch(`http://localhost:${handle.port}/api/config`, { method: 'HEAD' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
+ const res = await fetch(`http://127.0.0.1:${handle.port}/api/config`, { method: 'HEAD' });
expect(res.status).toBe(200);
const body = await res.text();
expect(body).toBe('');
});
test('unknown path returns 404 when no static assets present (tmp dir has no dist)', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { status } = await get(handle.port, '/does-not-exist');
expect([200, 404]).toContain(status);
});
test('GET / serves the SPA shell (rewrites to /index.html)', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const root = await get(handle.port, '/');
const indexHtml = await get(handle.port, '/index.html');
expect(root.status).toBe(indexHtml.status);
});
test('release() removes the ui.lock', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const lockPath = resolve(lockDir, 'ui.lock');
expect(existsSync(lockPath)).toBe(true);
@@ -441,8 +479,8 @@ describe('startUiServer', () => {
expect(handle.port).toBeGreaterThan(0);
expect(secondHandle.port).toBeGreaterThan(0);
expect(handle.port).not.toBe(secondHandle.port);
- const a = await fetch(`http://localhost:${handle.port}/api/config`);
- const b = await fetch(`http://localhost:${secondHandle.port}/api/config`);
+ const a = await fetch(`http://127.0.0.1:${handle.port}/api/config`);
+ const b = await fetch(`http://127.0.0.1:${secondHandle.port}/api/config`);
expect(a.status).toBe(200);
expect(b.status).toBe(200);
} finally {
@@ -453,7 +491,7 @@ describe('startUiServer', () => {
});
test('GET /api/pages is proxied to the collab server when server.lock is live', async () => {
- const upstream = createHttpServer((req, res) => {
+ const upstream = await startDualLoopbackUpstream((req, res) => {
if (req.url === '/api/pages') {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ ok: true, source: 'collab', pages: [] }));
@@ -462,13 +500,12 @@ describe('startUiServer', () => {
res.end();
}
});
- await new Promise<void>((done) => upstream.listen(0, 'localhost', () => done()));
- const upstreamPort = (upstream.address() as { port: number }).port;
+ const upstreamPort = upstream.port;
acquireServerLock(lockDir, { port: 0, worktreeRoot: tmpDir });
updateServerLockPort(lockDir, upstreamPort);
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
try {
const { status, body, headers } = await get(handle.port, '/api/pages');
expect(status).toBe(200);
@@ -476,12 +513,12 @@ describe('startUiServer', () => {
const parsed = JSON.parse(body);
expect(parsed).toEqual({ ok: true, source: 'collab', pages: [] });
} finally {
- await new Promise<void>((done) => upstream.close(() => done()));
+ await upstream.close();
}
});
test('GET /api/anything returns RFC 9457 problem+json 503 when server.lock is absent', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { status, body, headers } = await get(handle.port, '/api/pages');
expect(status).toBe(503);
expect(headers.get('content-type')).toContain('application/problem+json');
@@ -499,7 +536,7 @@ describe('startUiServer', () => {
test('POST /api/create-page forwards method + body to the collab server', async () => {
const receivedRequests: Array<{ method: string; body: string; contentType: string }> = [];
- const upstream = createHttpServer((req, res) => {
+ const upstream = await startDualLoopbackUpstream((req, res) => {
if (req.url === '/api/create-page' && req.method === 'POST') {
let body = '';
req.setEncoding('utf-8');
@@ -520,14 +557,13 @@ describe('startUiServer', () => {
res.end();
}
});
- await new Promise<void>((done) => upstream.listen(0, 'localhost', () => done()));
- const upstreamPort = (upstream.address() as { port: number }).port;
+ const upstreamPort = upstream.port;
acquireServerLock(lockDir, { port: 0, worktreeRoot: tmpDir });
updateServerLockPort(lockDir, upstreamPort);
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
try {
- const res = await fetch(`http://localhost:${handle.port}/api/create-page`, {
+ const res = await fetch(`http://127.0.0.1:${handle.port}/api/create-page`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ docName: 'notes/test', content: '# hi' }),
@@ -541,21 +577,21 @@ describe('startUiServer', () => {
const sent = JSON.parse(receivedRequests[0]?.body ?? '{}');
expect(sent).toEqual({ docName: 'notes/test', content: '# hi' });
} finally {
- await new Promise<void>((done) => upstream.close(() => done()));
+ await upstream.close();
}
});
test('/api/* proxy returns 502 when upstream connection fails', async () => {
const probe = createHttpServer();
- await new Promise<void>((done) => probe.listen(0, 'localhost', () => done()));
+ await new Promise<void>((done) => probe.listen(0, '127.0.0.1', () => done()));
const deadPort = (probe.address() as { port: number }).port;
await new Promise<void>((done) => probe.close(() => done()));
acquireServerLock(lockDir, { port: 0, worktreeRoot: tmpDir });
updateServerLockPort(lockDir, deadPort);
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
- const res = await fetch(`http://localhost:${handle.port}/api/pages`);
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
+ const res = await fetch(`http://127.0.0.1:${handle.port}/api/pages`);
expect(res.status).toBe(502);
});
@@ -578,7 +614,7 @@ describe('startUiServer', () => {
test('starts when the content root contains a broken symlink', async () => {
symlinkSync(resolve(tmpDir, 'missing-target'), resolve(tmpDir, 'broken-link'));
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { status } = await get(handle.port, '/api/config');
expect(status).toBe(200);
});
@@ -588,7 +624,7 @@ describe('startUiServer', () => {
const seedFile = resolve(tmpDir, 'doc.md');
fs.writeFileSync(seedFile, '# seed', 'utf-8');
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { status, headers } = await get(handle.port, '/missing.m4v');
expect(status).toBe(404);
expect(headers.get('content-type') ?? '').not.toMatch(/^text\/html/);
@@ -601,7 +637,7 @@ describe('startUiServer', () => {
const seedAsset = resolve(tmpDir, 'photo.png');
fs.writeFileSync(seedAsset, 'fake-png', 'binary');
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { status, headers } = await get(handle.port, '/photo.png');
expect(status).toBe(200);
expect(headers.get('content-disposition')).toBe('inline');
@@ -614,7 +650,7 @@ describe('startUiServer', () => {
const fontFile = readdirSync(distAssets).find((name) => name.endsWith('.woff2'));
if (!fontFile) return; // Build emitted no fonts — nothing to assert.
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { status, headers } = await get(handle.port, `/assets/${fontFile}`);
expect(status).toBe(200);
expect(headers.get('content-disposition')).toBeNull();
@@ -626,7 +662,7 @@ describe('startUiServer', () => {
config: config(),
cwd: tmpDir,
port: 0,
- host: 'localhost',
+ host: '127.0.0.1',
assetDir: distDir,
});
@@ -651,7 +687,7 @@ describe('startUiServer', () => {
config: config(),
cwd: tmpDir,
port: 0,
- host: 'localhost',
+ host: '127.0.0.1',
assetDir: distDir,
});
@@ -670,17 +706,17 @@ describe('startUiServer', () => {
config: config(),
cwd: tmpDir,
port: 0,
- host: 'localhost',
+ host: '127.0.0.1',
assetDir: distDir,
});
- const first = await fetch(`http://localhost:${handle.port}/assets/app-AAAA.js`);
+ const first = await fetch(`http://127.0.0.1:${handle.port}/assets/app-AAAA.js`);
expect(first.status).toBe(200);
const etag = first.headers.get('etag');
expect(etag).toBeTruthy();
expect(first.headers.get('cache-control') ?? '').not.toBe('no-store');
- const second = await fetch(`http://localhost:${handle.port}/assets/app-AAAA.js`, {
+ const second = await fetch(`http://127.0.0.1:${handle.port}/assets/app-AAAA.js`, {
headers: { 'If-None-Match': etag as string },
});
expect(second.status).toBe(304);
@@ -693,7 +729,7 @@ describe('startUiServer', () => {
fs.writeFileSync(resolve(tmpDir, 'doc.md'), '# seed', 'utf-8');
fs.writeFileSync(resolve(assetsDir, 'user-upload.png'), 'fake-png', 'binary');
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { status, headers } = await get(handle.port, '/assets/user-upload.png');
expect(status).toBe(200);
expect(headers.get('content-disposition')).toBe('inline');
@@ -707,7 +743,7 @@ describe('startUiServer', () => {
const seedHtml = resolve(tmpDir, 'viewer.html');
fs.writeFileSync(seedHtml, '<h1>viewer</h1><script>alert(1)</script>', 'utf-8');
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { status, headers } = await get(handle.port, '/viewer.html');
expect(status).toBe(200);
expect(headers.get('content-disposition')).toBe('inline');
@@ -723,7 +759,7 @@ describe('startUiServer', () => {
config: config(),
cwd: tmpDir,
port: 0,
- host: 'localhost',
+ host: '127.0.0.1',
assetDir: dist,
});
const { status, headers } = await get(handle.port, '/index.html');
@@ -733,7 +769,7 @@ describe('startUiServer', () => {
});
test('/api/* gate rejects requests with non-loopback Host header (DNS-rebind defense)', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const res = await rawRequest({
port: handle.port,
path: '/api/config',
@@ -747,7 +783,7 @@ describe('startUiServer', () => {
});
test('/api/* gate rejects requests with non-loopback Origin (CSRF defense)', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const res = await rawRequest({
port: handle.port,
path: '/api/config',
@@ -759,7 +795,7 @@ describe('startUiServer', () => {
});
test('/api/* gate accepts loopback Origin (legitimate Vite dev server)', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const res = await rawRequest({
port: handle.port,
path: '/api/config',
@@ -769,7 +805,7 @@ describe('startUiServer', () => {
});
test('/api/* gate accepts Origin: null (Electron packaged renderer)', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const res = await rawRequest({
port: handle.port,
path: '/api/config',
@@ -780,17 +816,16 @@ describe('startUiServer', () => {
test('/api/* proxy gate rejects DNS-rebind Host even when collab server is up', async () => {
let upstreamHits = 0;
- const upstream = createHttpServer((_req, res) => {
+ const upstream = await startDualLoopbackUpstream((_req, res) => {
upstreamHits++;
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ ok: true }));
});
- await new Promise<void>((done) => upstream.listen(0, 'localhost', () => done()));
- const upstreamPort = (upstream.address() as { port: number }).port;
+ const upstreamPort = upstream.port;
acquireServerLock(lockDir, { port: 0, worktreeRoot: tmpDir });
updateServerLockPort(lockDir, upstreamPort);
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
try {
const res = await rawRequest({
port: handle.port,
@@ -805,12 +840,12 @@ describe('startUiServer', () => {
expect(body.type).toBe('urn:ok:error:host-not-allowed');
expect(upstreamHits).toBe(0);
} finally {
- await new Promise<void>((done) => upstream.close(() => done()));
+ await upstream.close();
}
});
test('non-/api/* paths are NOT subject to the gate (Host check would harm SPA)', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const res = await rawRequest({
port: handle.port,
path: '/missing.png',
@@ -826,7 +861,7 @@ describe('startUiServer', () => {
const seedZip = resolve(tmpDir, 'archive.zip');
fs.writeFileSync(seedZip, 'fake-zip-bytes', 'binary');
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const { status, headers } = await get(handle.port, '/archive.zip');
expect(status).toBe(200);
expect(headers.get('content-disposition')).toBe('attachment');
@@ -845,7 +880,7 @@ describe('startUiServer — D-025 12h safety-net', () => {
config: config(),
cwd: tmpDir,
port: 0,
- host: 'localhost',
+ host: '127.0.0.1',
safetyNetMs: 60_000,
scheduler,
});
@@ -859,7 +894,7 @@ describe('startUiServer — D-025 12h safety-net', () => {
config: config(),
cwd: tmpDir,
port: 0,
- host: 'localhost',
+ host: '127.0.0.1',
safetyNetMs: 60_000,
scheduler,
onSafetyNet: () => {
@@ -878,7 +913,7 @@ describe('startUiServer — D-025 12h safety-net', () => {
if (handle) await closeHttpServers(handle.httpServers);
let connectError: unknown = null;
try {
- await fetch(`http://localhost:${port}/api/config`);
+ await fetch(`http://127.0.0.1:${port}/api/config`);
} catch (err) {
connectError = err;
}
@@ -893,7 +928,7 @@ describe('startUiServer — D-025 12h safety-net', () => {
config: config(),
cwd: tmpDir,
port: 0,
- host: 'localhost',
+ host: '127.0.0.1',
safetyNetMs: 60_000,
scheduler,
onSafetyNet: () => {
@@ -915,7 +950,7 @@ describe('startUiServer — D-025 12h safety-net', () => {
config: config(),
cwd: tmpDir,
port: 0,
- host: 'localhost',
+ host: '127.0.0.1',
safetyNetMs: 60_000,
scheduler,
});
@@ -928,7 +963,7 @@ describe('startUiServer — D-025 12h safety-net', () => {
});
test('release() is idempotent — second call is a no-op', async () => {
- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
const lockPath = resolve(lockDir, 'ui.lock');
handle.release();
@@ -946,7 +981,7 @@ describe('startUiServer — D-025 12h safety-net', () => {
config: config(),
cwd: tmpDir,
port: 0,
- host: 'localhost',
+ host: '127.0.0.1',
safetyNetMs: 0,
scheduler,
});
@@ -968,7 +1003,7 @@ describe('resolveUiLockCollision', () => {
test('same port as holder → already-running', async () => {
const result = await resolveUiLockCollision({
requestedPort: 3000,
- host: 'localhost',
+ host: '127.0.0.1',
lockDir,
readLock: () => fakeLock(3000),
});
@@ -980,7 +1015,7 @@ describe('resolveUiLockCollision', () => {
await expect(
resolveUiLockCollision({
requestedPort: 3000,
- host: 'localhost',
+ host: '127.0.0.1',
lockDir,
readLock: () => null,
}),
@@ -988,16 +1023,15 @@ describe('resolveUiLockCollision', () => {
});
test('different port + live upstream → proxy mode forwards correctly', async () => {
- const upstream = createHttpServer((_req, res) => {
+ const upstream = await startDualLoopbackUpstream((_req, res) => {
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.end('upstream ok');
});
- await new Promise<void>((done) => upstream.listen(0, 'localhost', () => done()));
- const upstreamPort = (upstream.address() as { port: number }).port;
+ const upstreamPort = upstream.port;
const result = await resolveUiLockCollision({
requestedPort: 0, // kernel-allocated so we don't conflict with anything
- host: 'localhost',
+ host: '127.0.0.1',
lockDir,
readLock: () => fakeLock(upstreamPort),
});
@@ -1007,31 +1041,31 @@ describe('resolveUiLockCollision', () => {
expect(result.upstreamPort).toBe(upstreamPort);
try {
- const response = await fetch(`http://localhost:${result.handle.port}/`);
+ const response = await fetch(`http://127.0.0.1:${result.handle.port}/`);
expect(response.status).toBe(200);
expect(await response.text()).toBe('upstream ok');
} finally {
await result.handle.close();
- await new Promise<void>((done) => upstream.close(() => done()));
+ await upstream.close();
}
});
test('proxy returns 502 when upstream dies', async () => {
const probe = createHttpServer();
- await new Promise<void>((done) => probe.listen(0, 'localhost', () => done()));
+ await new Promise<void>((done) => probe.listen(0, '127.0.0.1', () => done()));
const deadPort = (probe.address() as { port: number }).port;
await new Promise<void>((done) => probe.close(() => done()));
const result = await resolveUiLockCollision({
requestedPort: 0,
- host: 'localhost',
+ host: '127.0.0.1',
lockDir,
readLock: () => fakeLock(deadPort),
});
if (result.mode !== 'proxy') throw new Error('unreachable');
try {
- const response = await fetch(`http://localhost:${result.handle.port}/`);
+ const response = await fetch(`http://127.0.0.1:${result.handle.port}/`);
expect(response.status).toBe(502);
} finally {
await result.handle.close();
@@ -1039,9 +1073,8 @@ describe('resolveUiLockCollision', () => {
});
test('lock port=0 that becomes live within deadline → proxy mode', async () => {
- const upstream = createHttpServer((_req, res) => res.end('late upstream'));
- await new Promise<void>((done) => upstream.listen(0, 'localhost', () => done()));
- const upstreamPort = (upstream.address() as { port: number }).port;
+ const upstream = await startDualLoopbackUpstream((_req, res) => res.end('late upstream'));
+ const upstreamPort = upstream.port;
let calls = 0;
const readLock = () => {
@@ -1051,7 +1084,7 @@ describe('resolveUiLockCollision', () => {
const result = await resolveUiLockCollision({
requestedPort: 0,
- host: 'localhost',
+ host: '127.0.0.1',
lockDir,
readLock,
pollIntervalMs: 10,
@@ -1063,14 +1096,14 @@ describe('resolveUiLockCollision', () => {
expect(result.upstreamPort).toBe(upstreamPort);
await result.handle.close();
- await new Promise<void>((done) => upstream.close(() => done()));
+ await upstream.close();
});
test('lock port=0 that stays 0 → throws timeout error', async () => {
await expect(
resolveUiLockCollision({
requestedPort: 3000,
- host: 'localhost',
+ host: '127.0.0.1',
lockDir,
readLock: () => fakeLock(0),
pollIntervalMs: 5,
@@ -1088,7 +1121,7 @@ describe('resolveUiLockCollision', () => {
const result = await resolveUiLockCollision({
requestedPort: 4321,
- host: 'localhost',
+ host: '127.0.0.1',
lockDir,
readLock,
pollIntervalMs: 5,
diff --git a/packages/cli/src/loopback-bind-discipline.test.ts b/packages/cli/src/loopback-bind-discipline.test.ts
new file mode 100644
index 000000000..b4081b1fd
--- /dev/null
+++ b/packages/cli/src/loopback-bind-discipline.test.ts
@@ -0,0 +1,175 @@
+import { describe, expect, test } from 'bun:test';
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, '..');
+const SCAN_ROOT = __dirname; // packages/cli/src
+
+const SELF_BASENAME = basename(fileURLToPath(import.meta.url));
+
+interface FileLines {
+ path: string;
+ lines: string[];
+}
+
+function listScannedTestFiles(): FileLines[] {
+ const out: FileLines[] = [];
+ function walk(dir: string) {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const abs = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ walk(abs);
+ continue;
+ }
+ if (!entry.isFile() || !entry.name.endsWith('.test.ts')) continue;
+ if (entry.name === SELF_BASENAME) continue;
+ out.push({
+ path: relative(PACKAGE_ROOT, abs),
+ lines: readFileSync(abs, 'utf-8').split('\n'),
+ });
+ }
+ }
+ walk(SCAN_ROOT);
+ return out;
+}
+
+function isCommentOnlyLine(line: string): boolean {
+ const trimmed = line.trim();
+ return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');
+}
+
+const LOOPBACK_HOST_LITERAL = /['"](?:127\.0\.0\.1|::1)['"]/;
+
+export function findNonLoopbackListenCalls(lines: string[]): Array<{ line: number; text: string }> {
+ const violations: Array<{ line: number; text: string }> = [];
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i] ?? '';
+ if (isCommentOnlyLine(line)) continue;
+ const idx = line.indexOf('.listen(');
+ if (idx === -1) continue;
+ let window = line.slice(idx);
+ for (let j = i + 1; j <= i + 3 && !window.includes(')') && j < lines.length; j++) {
+ window += `\n${lines[j] ?? ''}`;
+ }
+ const paren = window.indexOf(')');
+ if (paren !== -1) window = window.slice(0, paren + 1);
+ if (!LOOPBACK_HOST_LITERAL.test(window)) {
+ violations.push({ line: i + 1, text: line.trim() });
+ }
+ }
+ return violations;
+}
+
+const AMBIGUOUS_LOCALHOST_DIAL = /\b(?:https?|wss?):\/\/localhost:\$\{/;
+
+export function findAmbiguousLocalhostDials(
+ lines: string[],
+): Array<{ line: number; text: string }> {
+ const violations: Array<{ line: number; text: string }> = [];
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i] ?? '';
+ if (isCommentOnlyLine(line)) continue;
+ if (AMBIGUOUS_LOCALHOST_DIAL.test(line)) {
+ violations.push({ line: i + 1, text: line.trim() });
+ }
+ }
+ return violations;
+}
+
+describe('loopback bind discipline (cli test sources)', () => {
+ const files = listScannedTestFiles();
+
+ test('there are test files to scan (sanity)', () => {
+ expect(files.length).toBeGreaterThan(0);
+ expect(files.some((f) => f.path.endsWith('commands/ui.test.ts'))).toBe(true);
+ expect(files.some((f) => f.path.endsWith('commands/ui-proxy.test.ts'))).toBe(true);
+ });
+
+ test('every .listen( call binds an explicit loopback host literal', () => {
+ const violations: string[] = [];
+ for (const file of files) {
+ for (const v of findNonLoopbackListenCalls(file.lines)) {
+ violations.push(` ${file.path}:${v.line} ${v.text}`);
+ }
+ }
+ if (violations.length > 0) {
+ throw new Error(
+ `Hostless rig bind found — a bare listen(0) binds the IPv6 wildcard '::', whose loopback-specific ` +
+ `port slots stay silently bindable by foreign processes; their listeners then intercept this rig's ` +
+ `localhost dials (the rotating integration-suite flake). Bind a loopback-specific host ` +
+ `(e.g. listen(0, '127.0.0.1', cb)) and dial the literal from server.address():\n${violations.join('\n')}`,
+ );
+ }
+ });
+
+ test('no interpolated-port localhost dial URLs', () => {
+ const violations: string[] = [];
+ for (const file of files) {
+ for (const v of findAmbiguousLocalhostDials(file.lines)) {
+ violations.push(` ${file.path}:${v.line} ${v.text}`);
+ }
+ }
+ if (violations.length > 0) {
+ throw new Error(
+ `Ambiguous-name rig dial found — 'localhost' resolves '::1'-first, exactly the loopback-specific slot ` +
+ `a foreign process can hold while the rig sits on a wildcard (or single-family) bind. Dial the ` +
+ `literal address the rig actually bound (a rig-advertised base URL, or ` +
+ `http://127.0.0.1:\${port}):\n${violations.join('\n')}`,
+ );
+ }
+ });
+
+ test('listen predicate fires on planted violations and not on adjacent negatives', () => {
+ expect(findNonLoopbackListenCalls([' s.listen(0, () => {']).length).toBe(1);
+ expect(
+ findNonLoopbackListenCalls([' httpServer.listen(port, () => resolve());']).length,
+ ).toBe(1);
+
+ expect(findNonLoopbackListenCalls([" server.listen(0, 'localhost', cb);"]).length).toBe(1);
+
+ expect(findNonLoopbackListenCalls([" server.listen(0, '127.0.0.1', resolve);"]).length).toBe(
+ 0,
+ );
+ expect(findNonLoopbackListenCalls([" s.listen(port, '::1', cb);"]).length).toBe(0);
+
+ expect(
+ findNonLoopbackListenCalls([' server.listen(', ' 0,', " '127.0.0.1',", ' cb)'])
+ .length,
+ ).toBe(0);
+
+ expect(findNonLoopbackListenCalls([' // before httpServer.listen() resolves']).length).toBe(0);
+ expect(
+ findNonLoopbackListenCalls([' * boot scan runs BEFORE httpServer.listen().']).length,
+ ).toBe(0);
+
+ expect(findNonLoopbackListenCalls([' s.listen(port, host, cb);']).length).toBe(1);
+
+ expect(findNonLoopbackListenCalls([" s.listen(0, '0.0.0.0', cb);"]).length).toBe(1);
+ });
+
+ test('dial predicate fires on planted violations and not on adjacent negatives', () => {
+ expect(
+ findAmbiguousLocalhostDials([
+ ` const res = await fetch(\`http://localhost:\${handle.port}/api/config\`);`,
+ ]).length,
+ ).toBe(1);
+ expect(
+ findAmbiguousLocalhostDials([` url: \`ws://localhost:\${port}/collab\`,`]).length,
+ ).toBe(1);
+
+ expect(
+ findAmbiguousLocalhostDials([` const res = await fetch(\`http://127.0.0.1:\${port}/x\`);`])
+ .length,
+ ).toBe(0);
+
+ expect(findAmbiguousLocalhostDials([" origin: 'http://localhost:5173',"]).length).toBe(0);
+
+ expect(findAmbiguousLocalhostDials([` // dials http://localhost:\${port} today`]).length).toBe(
+ 0,
+ );
+
+ expect(findAmbiguousLocalhostDials([" host: 'localhost:5173',"]).length).toBe(0);
+ });
+});
diff --git a/packages/server/src/api-asset.test.ts b/packages/server/src/api-asset.test.ts
index 77f56d398..035b57e2f 100644
--- a/packages/server/src/api-asset.test.ts
+++ b/packages/server/src/api-asset.test.ts
@@ -6,6 +6,7 @@ import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { createApiExtension } from './api-extension.ts';
import type { ContentFilter } from './content-filter.ts';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
interface Harness {
baseURL: string;
@@ -30,14 +31,10 @@ async function startHarness(contentDir: string, contentFilter?: ContentFilter):
).onRequest({ request: req, response: res });
});
- await new Promise<void>((resolve) => server.listen(0, resolve));
- const address = server.address();
- if (typeof address !== 'object' || address === null) {
- throw new Error('server did not bind to a port');
- }
+ const { baseUrl } = await listenOnLoopback(server);
return {
- baseURL: `http://127.0.0.1:${address.port}`,
+ baseURL: baseUrl,
close: () =>
new Promise<void>((resolve, reject) => {
server.close((err) => (err ? reject(err) : resolve()));
diff --git a/packages/server/src/api-extension.branch-info.test.ts b/packages/server/src/api-extension.branch-info.test.ts
index 4e9b30d3e..79b5b576d 100644
--- a/packages/server/src/api-extension.branch-info.test.ts
+++ b/packages/server/src/api-extension.branch-info.test.ts
@@ -4,6 +4,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import type { Server } from 'node:http';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
interface TestRig {
port: number;
@@ -71,12 +72,7 @@ async function bootRig(
});
hocuspocus.configuration.extensions.push(ext);
- const port = await new Promise<number>((resolveListen) => {
- server.listen(0, () => {
- const addr = server.address();
- resolveListen(typeof addr === 'object' && addr ? addr.port : 0);
- });
- });
+ const { port } = await listenOnLoopback(server);
return {
port,
@@ -92,7 +88,7 @@ async function bootRig(
function buildUrl(port: number, branch: string, path: string, kind?: 'doc' | 'folder'): string {
const params = new URLSearchParams({ branch, path });
if (kind) params.set('kind', kind);
- return `http://localhost:${port}/api/git/branch-info?${params.toString()}`;
+ return `http://127.0.0.1:${port}/api/git/branch-info?${params.toString()}`;
}
async function getBranchInfo(
@@ -272,7 +268,7 @@ describe('GET /api/git/branch-info', () => {
commitAll(projectDir, 'init');
});
- const res = await fetch(`http://localhost:${rig.port}/api/git/branch-info?branch=main`);
+ const res = await fetch(`http://127.0.0.1:${rig.port}/api/git/branch-info?branch=main`);
expect(res.status).toBe(400);
});
@@ -283,7 +279,7 @@ describe('GET /api/git/branch-info', () => {
commitAll(projectDir, 'init');
});
- const res = await fetch(`http://localhost:${rig.port}/api/git/branch-info?path=a.md`);
+ const res = await fetch(`http://127.0.0.1:${rig.port}/api/git/branch-info?path=a.md`);
expect(res.status).toBe(400);
});
@@ -387,7 +383,7 @@ describe('GET /api/git/branch-info', () => {
});
const res = await fetch(
- `http://localhost:${rig.port}/api/git/branch-info?branch=main&path=&kind=folder`,
+ `http://127.0.0.1:${rig.port}/api/git/branch-info?branch=main&path=&kind=folder`,
);
expect(res.status).toBe(200);
const json = (await res.json()) as Record<string, unknown>;
@@ -401,7 +397,7 @@ describe('GET /api/git/branch-info', () => {
commitAll(projectDir, 'init');
});
- const res = await fetch(`http://localhost:${rig.port}/api/git/branch-info?branch=main&path=`);
+ const res = await fetch(`http://127.0.0.1:${rig.port}/api/git/branch-info?branch=main&path=`);
expect(res.status).toBe(400);
});
diff --git a/packages/server/src/api-extension.checkout.test.ts b/packages/server/src/api-extension.checkout.test.ts
index a00073c02..5837d3d72 100644
--- a/packages/server/src/api-extension.checkout.test.ts
+++ b/packages/server/src/api-extension.checkout.test.ts
@@ -4,6 +4,7 @@ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'nod
import type { Server } from 'node:http';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
interface TestRig {
port: number;
@@ -75,12 +76,7 @@ async function bootRig(
});
hocuspocus.configuration.extensions.push(ext);
- const port = await new Promise<number>((resolveListen) => {
- server.listen(0, () => {
- const addr = server.address();
- resolveListen(typeof addr === 'object' && addr ? addr.port : 0);
- });
- });
+ const { port } = await listenOnLoopback(server);
return {
port,
@@ -97,7 +93,7 @@ async function postCheckout(
port: number,
body: Record<string, unknown>,
): Promise<{ status: number; json: Record<string, unknown> }> {
- const res = await fetch(`http://localhost:${port}/api/git/checkout`, {
+ const res = await fetch(`http://127.0.0.1:${port}/api/git/checkout`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(body),
@@ -341,7 +337,7 @@ describe('POST /api/git/checkout', () => {
commitAll(projectDir, 'init');
});
- const res = await fetch(`http://localhost:${rig.port}/api/git/checkout`);
+ const res = await fetch(`http://127.0.0.1:${rig.port}/api/git/checkout`);
expect(res.status).toBe(405);
});
diff --git a/packages/server/src/api-extension.ok-init.test.ts b/packages/server/src/api-extension.ok-init.test.ts
index 006279818..2f78e7a67 100644
--- a/packages/server/src/api-extension.ok-init.test.ts
+++ b/packages/server/src/api-extension.ok-init.test.ts
@@ -12,6 +12,7 @@ import {
import type { Server } from 'node:http';
import { homedir, tmpdir } from 'node:os';
import { join } from 'node:path';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
function extractHandlerBlock(src: string, handlerNameConst: string): string {
const anchorRe = new RegExp(`const\\s+${handlerNameConst}\\s*=`);
@@ -78,12 +79,7 @@ async function bootRig(): Promise<TestRig> {
});
hocuspocus.configuration.extensions.push(ext);
- const port = await new Promise<number>((resolveListen) => {
- server.listen(0, () => {
- const addr = server.address();
- resolveListen(typeof addr === 'object' && addr ? addr.port : 0);
- });
- });
+ const { port } = await listenOnLoopback(server);
return {
port,
@@ -101,7 +97,7 @@ async function postOkInit(
port: number,
body: Record<string, unknown>,
): Promise<{ status: number; json: Record<string, unknown> }> {
- const res = await fetch(`http://localhost:${port}/api/local-op/ok-init`, {
+ const res = await fetch(`http://127.0.0.1:${port}/api/local-op/ok-init`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(body),
diff --git a/packages/server/src/api-extension.test.ts b/packages/server/src/api-extension.test.ts
index 13dae834d..c7432e5c2 100644
--- a/packages/server/src/api-extension.test.ts
+++ b/packages/server/src/api-extension.test.ts
@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { resumeSyncOnAuthEvent, safeSubdir, sanitizeFilename } from './api-extension.ts';
import type { AuthEvent } from './local-ops/types.ts';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
import type { SyncEngine } from './sync-engine.ts';
describe('safeSubdir', () => {
@@ -190,12 +191,7 @@ describe('handleUploadAsset', () => {
hocuspocus.configuration.extensions.push(ext);
- port = await new Promise<number>((res) => {
- server.listen(0, () => {
- const addr = server.address();
- res(typeof addr === 'object' && addr ? addr.port : 0);
- });
- });
+ ({ port } = await listenOnLoopback(server));
});
afterEach(async () => {
@@ -224,7 +220,7 @@ describe('handleUploadAsset', () => {
const formData = new FormData();
formData.append('parentDocName', parentDocName);
formData.append('file', new Blob([file]), filename);
- return fetch(`http://localhost:${port}/api/upload`, {
+ return fetch(`http://127.0.0.1:${port}/api/upload`, {
method: 'POST',
body: formData,
});
@@ -245,7 +241,7 @@ describe('handleUploadAsset', () => {
test('rejects missing parentDocName', async () => {
const formData = new FormData();
formData.append('file', new Blob([createPngBuffer()]), 'test.png');
- const res = await fetch(`http://localhost:${port}/api/upload`, {
+ const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {
method: 'POST',
body: formData,
});
@@ -353,7 +349,7 @@ describe('handleUploadAsset', () => {
const formData = new FormData();
formData.append('parentDocName', 'docs/guide.md');
formData.append('file', new Blob([createPngBuffer()]), 'screenshot.png');
- const res = await fetch(`http://localhost:${port}/api/upload`, {
+ const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {
method: 'POST',
body: formData,
});
@@ -369,7 +365,7 @@ describe('handleUploadAsset', () => {
const formData = new FormData();
formData.append('parentDocName', 'docs/guide.md');
formData.append('file', new Blob([pdfBuffer]), 'draft.pdf');
- const res = await fetch(`http://localhost:${port}/api/upload`, {
+ const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {
method: 'POST',
body: formData,
});
@@ -384,7 +380,7 @@ describe('handleUploadAsset', () => {
const formData = new FormData();
formData.append('parentDocName', 'docs/guide.md');
formData.append('file', new Blob([csvBuffer]), 'data.csv');
- const res = await fetch(`http://localhost:${port}/api/upload`, {
+ const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {
method: 'POST',
body: formData,
});
@@ -449,12 +445,7 @@ describe('handleUploadAsset — same-dir sha256 dedup (FR-2)', () => {
hocuspocus.configuration.extensions.push(ext);
- port = await new Promise<number>((res) => {
- server.listen(0, () => {
- const addr = server.address();
- res(typeof addr === 'object' && addr ? addr.port : 0);
- });
- });
+ ({ port } = await listenOnLoopback(server));
});
afterEach(async () => {
@@ -473,7 +464,7 @@ describe('handleUploadAsset — same-dir sha256 dedup (FR-2)', () => {
const formData = new FormData();
formData.append('parentDocName', parent);
formData.append('file', new Blob([buf]), filename);
- return fetch(`http://localhost:${port}/api/upload`, { method: 'POST', body: formData });
+ return fetch(`http://127.0.0.1:${port}/api/upload`, { method: 'POST', body: formData });
}
test('second upload of identical bytes into same dir → deduped:true, single file on disk', async () => {
diff --git a/packages/server/src/asset-serve-middleware.integration.test.ts b/packages/server/src/asset-serve-middleware.integration.test.ts
index 20f84a8e6..7b8e9b03c 100644
--- a/packages/server/src/asset-serve-middleware.integration.test.ts
+++ b/packages/server/src/asset-serve-middleware.integration.test.ts
@@ -11,6 +11,7 @@ import {
import sirv from 'sirv';
import { createAssetServeMiddleware } from './asset-serve-middleware.ts';
import { createContentFilter } from './content-filter.ts';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
interface Harness {
baseURL: string;
@@ -38,12 +39,7 @@ async function startHarness(contentDir: string): Promise<Harness> {
});
});
- await new Promise<void>((resolve) => server.listen(0, resolve));
- const address = server.address();
- if (typeof address !== 'object' || address === null) {
- throw new Error('server did not bind to a port');
- }
- const baseURL = `http://127.0.0.1:${address.port}`;
+ const { baseUrl: baseURL } = await listenOnLoopback(server);
return {
baseURL,
diff --git a/packages/server/src/boot.test.ts b/packages/server/src/boot.test.ts
index dfd189479..4f879c4fe 100644
--- a/packages/server/src/boot.test.ts
+++ b/packages/server/src/boot.test.ts
@@ -48,6 +48,7 @@ describe('bootServer — MissingOkConfigError pre-listen check', () => {
let caught: unknown;
try {
await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
@@ -79,6 +80,7 @@ describe('bootServer — MissingOkConfigError pre-listen check', () => {
let caught: unknown;
try {
await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
@@ -109,6 +111,7 @@ describe('bootServer — MissingOkConfigError pre-listen check', () => {
let booted: Awaited<ReturnType<typeof bootServer>> | null = null;
try {
booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
projectDir,
@@ -134,6 +137,7 @@ describe('bootServer — MissingOkConfigError pre-listen check', () => {
let caught: unknown;
try {
await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
projectDir,
@@ -168,6 +172,7 @@ describe('bootServer — MissingOkConfigError pre-listen check', () => {
let booted: Awaited<ReturnType<typeof bootServer>> | null = null;
try {
booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
@@ -196,6 +201,7 @@ describe('bootServer — runtime state lives at projectDir, not contentDir', ()
mkdirSync(contentDir, { recursive: true });
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir,
@@ -264,6 +270,7 @@ describe('bootServer — idle-shutdown runs full destroy', () => {
seedOkScaffold(projectDir);
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: projectDir,
port: 0,
@@ -297,6 +304,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {
writeFileSync(resolve(shellDistDir, 'index.html'), '<html>shell</html>', 'utf-8');
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir: projectDir,
@@ -327,6 +335,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {
seedOkScaffold(projectDir);
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: projectDir,
port: 0,
@@ -366,6 +375,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {
writeFileSync(resolve(lockDir, 'ui.lock'), JSON.stringify(peerSnapshot), 'utf-8');
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir: projectDir,
@@ -424,6 +434,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {
);
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir: projectDir,
@@ -457,6 +468,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {
writeFileSync(resolve(shellDistDir, 'index.html'), '<html>shell</html>', 'utf-8');
const booted1 = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir: projectDir,
@@ -474,6 +486,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {
expect(existsSync(uiLockPath)).toBe(false);
const booted2 = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir: projectDir,
@@ -523,6 +536,7 @@ describe('bootServer — reactShellDistDir end-to-end HTTP shape', () => {
writeFileSync(resolve(projectDir, 'assets', 'upload.png'), uploadBytes);
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir: projectDir,
@@ -536,7 +550,7 @@ describe('bootServer — reactShellDistDir end-to-end HTTP shape', () => {
});
try {
await booted.ready;
- const base = `http://localhost:${booted.port}`;
+ const base = `http://127.0.0.1:${booted.port}`;
const rootRes = await fetch(`${base}/`);
expect(rootRes.status).toBe(200);
@@ -620,6 +634,7 @@ describe('bootServer — ok.boot OTel span attributes', () => {
seedOkScaffold(contentDir);
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
@@ -664,6 +679,7 @@ describe('bootServer — ok.boot OTel span attributes', () => {
seedOkScaffold(wtPath);
const booted = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: wtPath,
port: 0,
@@ -692,6 +708,7 @@ describe('bootServer — ok.boot OTel span attributes', () => {
let caught: unknown;
try {
await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
@@ -716,6 +733,7 @@ describe('bootServer — ok.boot OTel span attributes', () => {
await execFileAsync('git', ['init', '--initial-branch=main', mainDir]);
seedOkScaffold(mainDir);
const bootedMain = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: mainDir,
port: 0,
@@ -746,6 +764,7 @@ describe('bootServer — ok.boot OTel span attributes', () => {
]);
seedOkScaffold(wtPath);
const bootedLinked = await bootServer({
+ host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: wtPath,
port: 0,
diff --git a/packages/server/src/collab-message-limit.test.ts b/packages/server/src/collab-message-limit.test.ts
index 692f606bf..c2d7cbb3c 100644
--- a/packages/server/src/collab-message-limit.test.ts
+++ b/packages/server/src/collab-message-limit.test.ts
@@ -19,6 +19,7 @@ async function bootTestServer(): Promise<{ booted: BootedServer; contentDir: str
writeFileSync(join(okDir, 'config.yml'), '', 'utf-8');
writeFileSync(join(okDir, '.gitignore'), '', 'utf-8');
const booted = await bootServer({
+ host: '127.0.0.1',
contentDir,
attachUiSibling: false,
idleShutdownMs: null,
@@ -97,7 +98,7 @@ describe('collab WebSocket message size limits', () => {
const frame = makeOversizedSyncUpdate('test-doc', payloadBytes);
expect(frame.byteLength).toBe(MAX); // validates the layout constant above
- const ws = new WsClient(`ws://localhost:${booted.port}/collab`);
+ const ws = new WsClient(`ws://127.0.0.1:${booted.port}/collab`);
await new Promise<void>((resolve, reject) => {
ws.once('open', resolve);
ws.once('error', reject);
@@ -114,7 +115,7 @@ describe('collab WebSocket message size limits', () => {
expect(closedEarly).toBe(false);
expect(getMetrics().collabMessageTooLargeCount).toBe(0);
- const response = await fetch(`http://localhost:${booted.port}/api/server-info`, {
+ const response = await fetch(`http://127.0.0.1:${booted.port}/api/server-info`, {
signal: AbortSignal.timeout(1_000),
});
expect(response.ok).toBe(true);
@@ -132,13 +133,13 @@ describe('collab WebSocket message size limits', () => {
const { booted } = s;
const beforeRead = await fetch(
- `http://localhost:${booted.port}/api/document?docName=test-doc`,
+ `http://127.0.0.1:${booted.port}/api/document?docName=test-doc`,
{ signal: AbortSignal.timeout(1_000) },
);
expect(beforeRead.ok).toBe(true);
expect((await beforeRead.json()).content).toBe('# Test doc\n');
- const ws = new WsClient(`ws://localhost:${booted.port}/collab`);
+ const ws = new WsClient(`ws://127.0.0.1:${booted.port}/collab`);
await new Promise<void>((resolve, reject) => {
ws.once('open', resolve);
ws.once('error', reject);
@@ -152,13 +153,13 @@ describe('collab WebSocket message size limits', () => {
expect(close.code).toBe(1009);
expect(getMetrics().collabMessageTooLargeCount).toBe(1);
- const response = await fetch(`http://localhost:${booted.port}/api/server-info`, {
+ const response = await fetch(`http://127.0.0.1:${booted.port}/api/server-info`, {
signal: AbortSignal.timeout(1_000),
});
expect(response.ok).toBe(true);
const afterRead = await fetch(
- `http://localhost:${booted.port}/api/document?docName=test-doc`,
+ `http://127.0.0.1:${booted.port}/api/document?docName=test-doc`,
{
signal: AbortSignal.timeout(1_000),
},
diff --git a/packages/server/src/handoff-api.test.ts b/packages/server/src/handoff-api.test.ts
index 75113ad48..f459f9692 100644
--- a/packages/server/src/handoff-api.test.ts
+++ b/packages/server/src/handoff-api.test.ts
@@ -1,5 +1,4 @@
import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import type { AddressInfo } from 'node:net';
import { setTimeout as wait } from 'node:timers/promises';
import {
createInstalledAgentsProbe,
@@ -11,6 +10,7 @@ import {
type InstalledAgentScheme,
isLocalWebHost,
} from './handoff-api.ts';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
describe('createInstalledAgentsProbe', () => {
test('returns a record with exactly claude/codex/cursor keys', async () => {
@@ -445,12 +445,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
hocuspocus.configuration.extensions.push(ext);
- port = await new Promise<number>((resolve) => {
- server.listen(0, () => {
- const addr = server.address();
- resolve(addr && typeof addr === 'object' ? (addr as AddressInfo).port : 0);
- });
- });
+ ({ port } = await listenOnLoopback(server));
});
afterEach(async () => {
@@ -460,7 +455,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
});
test('GET returns 200 + flat boolean record matching injected probe', async () => {
- const res = await fetch(`http://localhost:${port}/api/installed-agents`);
+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`);
expect(res.status).toBe(200);
expect(res.headers.get('content-type')).toContain('application/json');
const body = await res.json();
@@ -469,14 +464,14 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
test('3 GETs within cache TTL trigger exactly 1 probe per scheme', async () => {
for (let i = 0; i < 3; i++) {
- const res = await fetch(`http://localhost:${port}/api/installed-agents`);
+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`);
expect(res.status).toBe(200);
}
expect(probeCalls).toEqual({ claude: 1, codex: 1, cursor: 1 });
});
test('POST returns 405 + RFC 9457 problem+json with Allow: GET', async () => {
- const res = await fetch(`http://localhost:${port}/api/installed-agents`, { method: 'POST' });
+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, { method: 'POST' });
expect(res.status).toBe(405);
expect(res.headers.get('Content-Type')).toBe('application/problem+json');
expect(res.headers.get('Allow')).toBe('GET');
@@ -491,7 +486,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
});
test('rejects cross-origin requests (DNS-rebinding / malicious-page defense)', async () => {
- const res = await fetch(`http://localhost:${port}/api/installed-agents`, {
+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {
headers: { Origin: 'https://evil.example.com' },
});
expect(res.status).toBe(403);
@@ -501,9 +496,9 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
expect(body.status).toBe(403);
});
- test('accepts same-origin browser requests (Origin: http://localhost)', async () => {
- const res = await fetch(`http://localhost:${port}/api/installed-agents`, {
- headers: { Origin: `http://localhost:${port}` },
+ test('accepts same-origin browser requests (Origin: http://127.0.0.1)', async () => {
+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {
+ headers: { Origin: `http://127.0.0.1:${port}` },
});
expect(res.status).toBe(200);
const body = await res.json();
@@ -511,7 +506,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
});
test('remote-web (Host: example.com) → all-true and probe NOT called', async () => {
- const res = await fetch(`http://localhost:${port}/api/installed-agents`, {
+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {
headers: {
Host: 'example.com:5173',
},
@@ -523,7 +518,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
});
test('remote-web (Host: 192.168.1.100) → all-true (LAN-bound dev server case)', async () => {
- const res = await fetch(`http://localhost:${port}/api/installed-agents`, {
+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {
headers: { Host: '192.168.1.100:5173' },
});
expect(res.status).toBe(200);
@@ -532,7 +527,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
});
test('local-web Host: 127.0.0.1 → real probe results', async () => {
- const res = await fetch(`http://localhost:${port}/api/installed-agents`, {
+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {
headers: { Host: `127.0.0.1:${port}` },
});
expect(res.status).toBe(200);
@@ -541,13 +536,13 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
});
test('remote-web requests are NOT cached against later local-web requests', async () => {
- const remote = await fetch(`http://localhost:${port}/api/installed-agents`, {
+ const remote = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {
headers: { Host: 'example.com:5173' },
});
expect(await remote.json()).toEqual({ claude: true, codex: true, cursor: true });
expect(probeCalls).toEqual({});
- const local = await fetch(`http://localhost:${port}/api/installed-agents`);
+ const local = await fetch(`http://127.0.0.1:${port}/api/installed-agents`);
expect(await local.json()).toEqual({ claude: true, codex: false, cursor: true });
expect(probeCalls).toEqual({ claude: 1, codex: 1, cursor: 1 });
});
diff --git a/packages/server/src/keepalive-presence-bootstrap.test.ts b/packages/server/src/keepalive-presence-bootstrap.test.ts
index 5315c80da..78c89c1eb 100644
--- a/packages/server/src/keepalive-presence-bootstrap.test.ts
+++ b/packages/server/src/keepalive-presence-bootstrap.test.ts
@@ -32,6 +32,7 @@ async function bootTestServer(): Promise<{ booted: BootedServer; contentDir: str
writeFileSync(join(okDir, 'config.yml'), '', 'utf-8');
writeFileSync(join(okDir, '.gitignore'), '', 'utf-8');
const booted = await bootServer({
+ host: '127.0.0.1',
contentDir,
attachUiSibling: false,
idleShutdownMs: null,
@@ -156,7 +157,7 @@ describe('keepalive WS upgrade → setPresence bootstrap', () => {
expect(broadcaster.getPresenceMap()[presenceKey]).toBeUndefined();
const ws = new WsClient(
- `ws://localhost:${booted.port}/collab/keepalive` +
+ `ws://127.0.0.1:${booted.port}/collab/keepalive` +
`?pid=${process.pid}` +
`&connectionId=${connectionId}` +
`&displayName=${encodeURIComponent('Claude')}` +
@@ -197,7 +198,7 @@ describe('keepalive WS upgrade → setPresence bootstrap', () => {
const presenceKey = toBroadcasterKey(connectionId);
const ws = new WsClient(
- `ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,
+ `ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,
);
await new Promise<void>((resolve, reject) => {
ws.once('open', () => resolve());
@@ -217,7 +218,7 @@ describe('keepalive WS upgrade → setPresence bootstrap', () => {
const presenceKey = toBroadcasterKey(connectionId);
const ws = new WsClient(
- `ws://localhost:${booted.port}/collab/keepalive` +
+ `ws://127.0.0.1:${booted.port}/collab/keepalive` +
`?pid=${process.pid}` +
`&connectionId=${connectionId}` +
`&displayName=${encodeURIComponent('Claude')}` +
@@ -246,7 +247,7 @@ describe('keepalive WS upgrade → setPresence bootstrap', () => {
`&clientName=${encodeURIComponent('claude')}` +
`&colorSeed=${encodeURIComponent('Claude')}`;
- const ws1 = new WsClient(`ws://localhost:${booted.port}/collab/keepalive${baseQuery}`);
+ const ws1 = new WsClient(`ws://127.0.0.1:${booted.port}/collab/keepalive${baseQuery}`);
await new Promise<void>((resolve, reject) => {
ws1.once('open', () => resolve());
ws1.once('error', (err) => reject(err));
@@ -261,7 +262,7 @@ describe('keepalive WS upgrade → setPresence bootstrap', () => {
ws1.close();
await wait(30);
- const ws2 = new WsClient(`ws://localhost:${booted.port}/collab/keepalive${baseQuery}`);
+ const ws2 = new WsClient(`ws://127.0.0.1:${booted.port}/collab/keepalive${baseQuery}`);
await new Promise<void>((resolve, reject) => {
ws2.once('open', () => resolve());
ws2.once('error', (err) => reject(err));
diff --git a/packages/server/src/keepalive-presence-cleanup.test.ts b/packages/server/src/keepalive-presence-cleanup.test.ts
index 26f75c196..319043628 100644
--- a/packages/server/src/keepalive-presence-cleanup.test.ts
+++ b/packages/server/src/keepalive-presence-cleanup.test.ts
@@ -33,6 +33,7 @@ async function bootTestServer(
writeFileSync(join(okDir, 'config.yml'), '', 'utf-8');
writeFileSync(join(okDir, '.gitignore'), '', 'utf-8');
const booted = await bootServer({
+ host: '127.0.0.1',
contentDir,
attachUiSibling: false,
idleShutdownMs: null,
@@ -87,7 +88,7 @@ describe('keepalive WS close → grace timer → clearPresence (US-004)', () =>
expect(broadcaster.getPresenceMap()[presenceKey]).toBeDefined();
const ws = new WsClient(
- `ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,
+ `ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,
);
await new Promise<void>((resolve, reject) => {
ws.once('open', () => resolve());
@@ -123,7 +124,7 @@ describe('keepalive WS close → grace timer → clearPresence (US-004)', () =>
});
const ws1 = new WsClient(
- `ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,
+ `ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,
);
await new Promise<void>((resolve, reject) => {
ws1.once('open', () => resolve());
@@ -133,7 +134,7 @@ describe('keepalive WS close → grace timer → clearPresence (US-004)', () =>
await wait(50);
const ws2 = new WsClient(
- `ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,
+ `ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,
);
await new Promise<void>((resolve, reject) => {
ws2.once('open', () => resolve());
@@ -162,7 +163,7 @@ describe('keepalive WS close → grace timer → clearPresence (US-004)', () =>
ts: Date.now(),
});
- const ws = new WsClient(`ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}`);
+ const ws = new WsClient(`ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}`);
await new Promise<void>((resolve, reject) => {
ws.once('open', () => resolve());
ws.once('error', (err) => reject(err));
@@ -181,7 +182,7 @@ describe('keepalive WS close → grace timer → clearPresence (US-004)', () =>
const presenceKey = toBroadcasterKey(connectionId);
const ws = new WsClient(
- `ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,
+ `ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,
);
await new Promise<void>((resolve, reject) => {
ws.once('open', () => resolve());
diff --git a/packages/server/src/loopback-bind-discipline.test.ts b/packages/server/src/loopback-bind-discipline.test.ts
new file mode 100644
index 000000000..b0dc9a40c
--- /dev/null
+++ b/packages/server/src/loopback-bind-discipline.test.ts
@@ -0,0 +1,176 @@
+import { describe, expect, test } from 'bun:test';
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, '..');
+const SCAN_ROOT = __dirname; // packages/server/src
+
+const SELF_BASENAME = basename(fileURLToPath(import.meta.url));
+
+interface FileLines {
+ path: string;
+ lines: string[];
+}
+
+function listScannedTestFiles(): FileLines[] {
+ const out: FileLines[] = [];
+ function walk(dir: string) {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const abs = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ walk(abs);
+ continue;
+ }
+ if (!entry.isFile() || !entry.name.endsWith('.test.ts')) continue;
+ if (entry.name === SELF_BASENAME) continue;
+ out.push({
+ path: relative(PACKAGE_ROOT, abs),
+ lines: readFileSync(abs, 'utf-8').split('\n'),
+ });
+ }
+ }
+ walk(SCAN_ROOT);
+ return out;
+}
+
+function isCommentOnlyLine(line: string): boolean {
+ const trimmed = line.trim();
+ return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');
+}
+
+const LOOPBACK_HOST_LITERAL = /['"](?:127\.0\.0\.1|::1)['"]/;
+
+export function findNonLoopbackListenCalls(lines: string[]): Array<{ line: number; text: string }> {
+ const violations: Array<{ line: number; text: string }> = [];
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i] ?? '';
+ if (isCommentOnlyLine(line)) continue;
+ const idx = line.indexOf('.listen(');
+ if (idx === -1) continue;
+ let window = line.slice(idx);
+ for (let j = i + 1; j <= i + 3 && !window.includes(')') && j < lines.length; j++) {
+ window += `\n${lines[j] ?? ''}`;
+ }
+ const paren = window.indexOf(')');
+ if (paren !== -1) window = window.slice(0, paren + 1);
+ if (!LOOPBACK_HOST_LITERAL.test(window)) {
+ violations.push({ line: i + 1, text: line.trim() });
+ }
+ }
+ return violations;
+}
+
+const AMBIGUOUS_LOCALHOST_DIAL = /\b(?:https?|wss?):\/\/localhost:\$\{/;
+
+export function findAmbiguousLocalhostDials(
+ lines: string[],
+): Array<{ line: number; text: string }> {
+ const violations: Array<{ line: number; text: string }> = [];
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i] ?? '';
+ if (isCommentOnlyLine(line)) continue;
+ if (AMBIGUOUS_LOCALHOST_DIAL.test(line)) {
+ violations.push({ line: i + 1, text: line.trim() });
+ }
+ }
+ return violations;
+}
+
+describe('loopback bind discipline (server test sources)', () => {
+ const files = listScannedTestFiles();
+
+ test('there are test files to scan (sanity)', () => {
+ expect(files.length).toBeGreaterThan(0);
+ expect(files.some((f) => f.path.endsWith('share/publish.integration.test.ts'))).toBe(true);
+ });
+
+ test('every .listen( call binds an explicit loopback host literal', () => {
+ const violations: string[] = [];
+ for (const file of files) {
+ for (const v of findNonLoopbackListenCalls(file.lines)) {
+ violations.push(` ${file.path}:${v.line} ${v.text}`);
+ }
+ }
+ if (violations.length > 0) {
+ throw new Error(
+ `Hostless rig bind found — a bare listen(0) binds the IPv6 wildcard '::', whose loopback-specific ` +
+ `port slots stay silently bindable by foreign processes; their listeners then intercept this rig's ` +
+ `localhost dials (the rotating share/git-context flake). Bind a loopback-specific host ` +
+ `(e.g. listen(0, '127.0.0.1', cb)) and dial the literal from server.address():\n${violations.join('\n')}`,
+ );
+ }
+ });
+
+ test('no interpolated-port localhost dial URLs', () => {
+ const violations: string[] = [];
+ for (const file of files) {
+ for (const v of findAmbiguousLocalhostDials(file.lines)) {
+ violations.push(` ${file.path}:${v.line} ${v.text}`);
+ }
+ }
+ if (violations.length > 0) {
+ throw new Error(
+ `Ambiguous-name rig dial found — 'localhost' resolves '::1'-first, exactly the loopback-specific slot ` +
+ `a foreign process can hold while the rig sits on a wildcard (or single-family) bind. Dial the ` +
+ `literal address the rig actually bound (e.g. http://127.0.0.1:\${port}):\n${violations.join('\n')}`,
+ );
+ }
+ });
+
+ test('listen predicate fires on planted violations and not on adjacent negatives', () => {
+ expect(findNonLoopbackListenCalls([' server.listen(0, () => {']).length).toBe(1);
+ expect(findNonLoopbackListenCalls([' await new Promise((r) => s.listen(0, r));']).length).toBe(
+ 1,
+ );
+ expect(
+ findNonLoopbackListenCalls([' httpServer.listen(port, () => resolve());']).length,
+ ).toBe(1);
+
+ expect(findNonLoopbackListenCalls([" server.listen(0, '127.0.0.1', resolve);"]).length).toBe(
+ 0,
+ );
+ expect(findNonLoopbackListenCalls([" s.listen(port, '::1', cb);"]).length).toBe(0);
+
+ expect(
+ findNonLoopbackListenCalls([' server.listen(', ' 0,', " '127.0.0.1',", ' cb)'])
+ .length,
+ ).toBe(0);
+
+ expect(findNonLoopbackListenCalls([' // before httpServer.listen() resolves']).length).toBe(0);
+ expect(
+ findNonLoopbackListenCalls([' * boot scan runs BEFORE httpServer.listen().']).length,
+ ).toBe(0);
+
+ expect(findNonLoopbackListenCalls([' s.listen(port, host, cb);']).length).toBe(1);
+
+ expect(findNonLoopbackListenCalls([" s.listen(0, '0.0.0.0', cb);"]).length).toBe(1);
+ });
+
+ test('dial predicate fires on planted violations and not on adjacent negatives', () => {
+ expect(
+ findAmbiguousLocalhostDials([
+ ` const res = await fetch(\`http://localhost:\${port}\${path}\`);`,
+ ]).length,
+ ).toBe(1);
+ expect(
+ findAmbiguousLocalhostDials([` url: \`ws://localhost:\${port}/collab\`,`]).length,
+ ).toBe(1);
+
+ expect(
+ findAmbiguousLocalhostDials([` const res = await fetch(\`http://127.0.0.1:\${port}/x\`);`])
+ .length,
+ ).toBe(0);
+
+ expect(
+ findAmbiguousLocalhostDials([" expect(url).toBe('ws://localhost:7777/collab');"]).length,
+ ).toBe(0);
+
+ expect(findAmbiguousLocalhostDials([` // dials http://localhost:\${port} today`]).length).toBe(
+ 0,
+ );
+
+ expect(findAmbiguousLocalhostDials([" host: 'localhost:5173',"]).length).toBe(0);
+ });
+});
diff --git a/packages/server/src/loopback-rig-test-helpers.ts b/packages/server/src/loopback-rig-test-helpers.ts
new file mode 100644
index 000000000..848bfad11
--- /dev/null
+++ b/packages/server/src/loopback-rig-test-helpers.ts
@@ -0,0 +1,44 @@
+import type { Server } from 'node:http';
+import { createServer } from 'node:http';
+
+export interface LoopbackListenResult {
+ port: number;
+ baseUrl: string;
+}
+
+export function listenOnLoopback(server: Server): Promise<LoopbackListenResult> {
+ return new Promise((resolve, reject) => {
+ server.once('error', reject);
+ server.listen(0, '127.0.0.1', () => {
+ const addr = server.address();
+ if (typeof addr !== 'object' || addr === null) {
+ server.removeListener('error', reject);
+ server.close(() =>
+ reject(new Error('listenOnLoopback: server.address() returned no port')),
+ );
+ return;
+ }
+ server.removeListener('error', reject);
+ resolve({ port: addr.port, baseUrl: `http://127.0.0.1:${addr.port}` });
+ });
+ });
+}
+
+export function getFreeLoopbackPort(): Promise<number> {
+ return new Promise((resolve, reject) => {
+ const probe = createServer();
+ probe.once('error', reject);
+ probe.listen(0, '127.0.0.1', () => {
+ const addr = probe.address();
+ if (typeof addr !== 'object' || addr === null) {
+ probe.removeListener('error', reject);
+ probe.close(() =>
+ reject(new Error('getFreeLoopbackPort: probe.address() returned no port')),
+ );
+ return;
+ }
+ const { port } = addr;
+ probe.close(() => resolve(port));
+ });
+ });
+}
diff --git a/packages/server/src/mcp-http.test.ts b/packages/server/src/mcp-http.test.ts
index 2a86ea789..ea7846fee 100644
--- a/packages/server/src/mcp-http.test.ts
+++ b/packages/server/src/mcp-http.test.ts
@@ -1,11 +1,11 @@
import { afterEach, beforeEach, expect, test } from 'bun:test';
import { mkdtempSync, rmSync } from 'node:fs';
import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
-import { type AddressInfo, createServer as createNetServer } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { type Config, ConfigSchema } from './config/schema.ts';
+import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';
import { MCP_CONNECTION_ID_HEADER } from './mcp/agent-identity.ts';
import {
createMcpHttpHandler,
@@ -21,22 +21,12 @@ interface SessionHarness {
cleanup: () => Promise<void>;
}
-async function getFreePort(): Promise<number> {
- return new Promise((res) => {
- const s = createNetServer();
- s.listen(0, () => {
- const port = (s.address() as AddressInfo).port;
- s.close(() => res(port));
- });
- });
-}
-
async function bootHandler(
config: Config,
handlerOptions: Partial<Pick<McpHttpHandlerOptions, 'log' | 'maxSessions' | 'sessionTtlMs'>> = {},
): Promise<SessionHarness> {
const contentDir = mkdtempSync(join(tmpdir(), 'ok-mcp-http-cfg-'));
- const port = await getFreePort();
+ const port = await getFreeLoopbackPort();
let handler: McpHttpHandler | null = null;
let httpServer: HttpServer | null = null;
try {
@@ -44,7 +34,7 @@ async function bootHandler(
contentDir,
projectDir: contentDir,
config,
- getServerUrl: () => `http://localhost:${port}`,
+ getServerUrl: () => `http://127.0.0.1:${port}`,
...handlerOptions,
});
@@ -65,7 +55,7 @@ async function bootHandler(
});
await new Promise<void>((res) => {
// biome-ignore lint/style/noNonNullAssertion: httpServer is set inside the try
- httpServer!.listen(port, () => res());
+ httpServer!.listen(port, '127.0.0.1', () => res());
});
} catch (err) {
if (httpServer) await new Promise<void>((res) => httpServer?.close(() => res()));
@@ -93,7 +83,7 @@ interface InitializedSession {
}
async function openMcpSession(port: number): Promise<InitializedSession> {
- const init = await fetch(`http://localhost:${port}/mcp`, {
+ const init = await fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
@@ -118,7 +108,7 @@ async function openMcpSession(port: number): Promise<InitializedSession> {
};
const protocolVersion = initBody.result?.protocolVersion ?? MCP_PROTOCOL_VERSION;
- const initialized = await fetch(`http://localhost:${port}/mcp`, {
+ const initialized = await fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
@@ -151,7 +141,7 @@ test('active MCP session cap refuses new sessions before allocation', async () =
await openMcpSession(harness.port);
- const second = await fetch(`http://localhost:${harness.port}/mcp`, {
+ const second = await fetch(`http://127.0.0.1:${harness.port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
@@ -181,7 +171,7 @@ test('mcp-tool-path-traversal: explicit cwd outside configured project root is r
const session = await openMcpSession(harness.port);
const callExec = async (cwd: string) =>
- fetch(`http://localhost:${harness.port}/mcp`, {
+ fetch(`http://127.0.0.1:${harness.port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
@@ -217,7 +207,7 @@ test('PRD-6659: tools/call write with an invalid position returns field name + a
const session = await openMcpSession(harness.port);
- const callRes = await fetch(`http://localhost:${harness.port}/mcp`, {
+ const callRes = await fetch(`http://127.0.0.1:${harness.port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
@@ -254,7 +244,7 @@ test('PRD-6659: tools/call write with an invalid position returns field name + a
test('forwarded connectionId header reaches /api/agent-write-md as agentId', async () => {
const config: Config = ConfigSchema.parse({});
const contentDir = mkdtempSync(join(tmpdir(), 'ok-mcp-http-cid-'));
- const port = await getFreePort();
+ const port = await getFreeLoopbackPort();
let handler: McpHttpHandler | null = null;
let httpServer: HttpServer | null = null;
let capturedAgentId: string | undefined;
@@ -264,7 +254,7 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asy
contentDir,
projectDir: contentDir,
config,
- getServerUrl: () => `http://localhost:${port}`,
+ getServerUrl: () => `http://127.0.0.1:${port}`,
});
httpServer = createHttpServer((req, res) => {
@@ -299,12 +289,12 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asy
});
await new Promise<void>((res) => {
// biome-ignore lint/style/noNonNullAssertion: httpServer set above
- httpServer!.listen(port, () => res());
+ httpServer!.listen(port, '127.0.0.1', () => res());
});
const forwarded = 'forwarded-keepalive-id-1234';
- const init = await fetch(`http://localhost:${port}/mcp`, {
+ const init = await fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
@@ -328,7 +318,7 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asy
const initBody = (await init.json()) as { result?: { protocolVersion?: string } };
const protocolVersion = initBody.result?.protocolVersion ?? MCP_PROTOCOL_VERSION;
- const initialized = await fetch(`http://localhost:${port}/mcp`, {
+ const initialized = await fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
@@ -340,7 +330,7 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asy
});
expect(initialized.status).toBe(202);
- const call = await fetch(`http://localhost:${port}/mcp`, {
+ const call = await fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
@@ -376,7 +366,7 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asy
test('invalid connectionId header is ignored — session falls back to a fresh UUID', async () => {
const config: Config = ConfigSchema.parse({});
const contentDir = mkdtempSync(join(tmpdir(), 'ok-mcp-http-cid-bad-'));
- const port = await getFreePort();
+ const port = await getFreeLoopbackPort();
let handler: McpHttpHandler | null = null;
let httpServer: HttpServer | null = null;
let capturedAgentId: string | undefined;
@@ -387,7 +377,7 @@ test('invalid connectionId header is ignored — session falls back to a fresh U
contentDir,
projectDir: contentDir,
config,
- getServerUrl: () => `http://localhost:${port}`,
+ getServerUrl: () => `http://127.0.0.1:${port}`,
log: {
warn: (obj, msg) => {
warnCalls.push({ obj, msg });
@@ -427,12 +417,12 @@ test('invalid connectionId header is ignored — session falls back to a fresh U
});
await new Promise<void>((res) => {
// biome-ignore lint/style/noNonNullAssertion: httpServer set above
- httpServer!.listen(port, () => res());
+ httpServer!.listen(port, '127.0.0.1', () => res());
});
const forwarded = 'bad value with spaces!';
- const init = await fetch(`http://localhost:${port}/mcp`, {
+ const init = await fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
@@ -454,7 +444,7 @@ test('invalid connectionId header is ignored — session falls back to a fresh U
const sessionId = init.headers.get('mcp-session-id') as string;
const initBody = (await init.json()) as { result?: { protocolVersion?: string } };
const protocolVersion = initBody.result?.protocolVersion ?? MCP_PROTOCOL_VERSION;
- await fetch(`http://localhost:${port}/mcp`, {
+ await fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
@@ -465,7 +455,7 @@ test('invalid connectionId header is ignored — session falls back to a fresh U
body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }),
});
- const call = await fetch(`http://localhost:${port}/mcp`, {
+ const call = await fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
@@ -516,7 +506,7 @@ test('inactive MCP sessions expire and return 404 on later use', async () => {
const session = await openMcpSession(harness.port);
await wait(350);
- const expired = await fetch(`http://localhost:${harness.port}/mcp`, {
+ const expired = await fetch(`http://127.0.0.1:${harness.port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
diff --git a/packages/server/src/mcp-mount.test.ts b/packages/server/src/mcp-mount.test.ts
index 2bdb7835d..4d9ace0f4 100644
--- a/packages/server/src/mcp-mount.test.ts
+++ b/packages/server/src/mcp-mount.test.ts
@@ -1,11 +1,7 @@
import { afterEach, describe, expect, test } from 'bun:test';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { createServer, type Server as HttpServer, request as httpRequest } from 'node:http';
-import {
- type AddressInfo,
- connect as createNetConnection,
- createServer as createNetServer,
-} from 'node:net';
+import { connect as createNetConnection } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { Hocuspocus } from '@hocuspocus/server';
@@ -16,6 +12,7 @@ import {
} from '@inkeep/open-knowledge-core';
import sirv from 'sirv';
import { createAssetServeMiddleware } from './asset-serve-middleware.ts';
+import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';
import type { McpHttpHandler } from './mcp-http.ts';
import {
type MountMcpAndApiHandle,
@@ -41,16 +38,6 @@ const hocuspocus = {
let servers: Array<{ httpServer: HttpServer; mount: MountMcpAndApiHandle }> = [];
-async function getFreePort(): Promise<number> {
- return new Promise((resolve) => {
- const server = createNetServer();
- server.listen(0, () => {
- const port = (server.address() as AddressInfo).port;
- server.close(() => resolve(port));
- });
- });
-}
-
async function startMountedServer(handler: McpHttpHandler): Promise<{ port: number }> {
const httpServer = createServer();
const mount = mountMcpAndApi({
@@ -59,7 +46,7 @@ async function startMountedServer(handler: McpHttpHandler): Promise<{ port: numb
mcpHttpHandler: handler,
log,
});
- const port = await getFreePort();
+ const port = await getFreeLoopbackPort();
await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
servers.push({ httpServer, mount });
return { port };
@@ -279,7 +266,7 @@ describe('mountMcpAndApi content-asset middleware', () => {
blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,
}),
});
- const port = await getFreePort();
+ const port = await getFreeLoopbackPort();
await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
servers.push({ httpServer, mount });
return { port };
@@ -334,7 +321,7 @@ describe('mountMcpAndApi content-asset middleware', () => {
throw new Error('simulated EMFILE');
},
});
- const port = await getFreePort();
+ const port = await getFreeLoopbackPort();
await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
servers.push({ httpServer, mount });
@@ -377,7 +364,7 @@ describe('mountMcpAndApi ephemeral content-asset gate', () => {
blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,
}),
});
- const port = await getFreePort();
+ const port = await getFreeLoopbackPort();
await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
servers.push({ httpServer, mount });
return { port };
@@ -440,7 +427,7 @@ describe('mountMcpAndApi react-shell middleware', () => {
immutable: true,
}),
});
- const port = await getFreePort();
+ const port = await getFreeLoopbackPort();
await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
servers.push({ httpServer, mount });
return { port, shellDir };
diff --git a/packages/server/src/mcp/tools/checkpoint.test.ts b/packages/server/src/mcp/tools/checkpoint.test.ts
index fcd9ca563..6dee2e505 100644
--- a/packages/server/src/mcp/tools/checkpoint.test.ts
+++ b/packages/server/src/mcp/tools/checkpoint.test.ts
@@ -57,6 +57,7 @@ const seenBodies: Array<Record<string, unknown>> = [];
beforeAll(() => {
testServer = Bun.serve({
port: 0,
+ hostname: '127.0.0.1',
async fetch(req) {
const url = new URL(req.url);
const body = req.method === 'POST' ? ((await req.json()) as Record<string, unknown>) : {};
@@ -70,7 +71,7 @@ beforeAll(() => {
return new Response('Not found', { status: 404 });
},
});
- baseUrl = `http://localhost:${testServer.port}`;
+ baseUrl = `http://127.0.0.1:${testServer.port}`;
});
afterAll(() => testServer.stop());
beforeEach(async () => {
diff --git a/packages/server/src/mcp/tools/conflicts.test.ts b/packages/server/src/mcp/tools/conflicts.test.ts
index 9582203c8..a15785e83 100644
--- a/packages/server/src/mcp/tools/conflicts.test.ts
+++ b/packages/server/src/mcp/tools/conflicts.test.ts
@@ -39,6 +39,7 @@ const cwd = mkdtempSync(join(tmpdir(), 'ok-conflicts-test-'));
beforeAll(() => {
testServer = Bun.serve({
port: 0,
+ hostname: '127.0.0.1',
fetch(req) {
const url = new URL(req.url);
if (url.pathname === '/api/sync/conflicts') {
@@ -61,7 +62,7 @@ beforeAll(() => {
return new Response('Not found', { status: 404 });
},
});
- baseUrl = `http://localhost:${testServer.port}`;
+ baseUrl = `http://127.0.0.1:${testServer.port}`;
});
afterAll(() => testServer.stop());
diff --git a/packages/server/src/mcp/tools/history.test.ts b/packages/server/src/mcp/tools/history.test.ts
index 4d98ffea3..dfbf211aa 100644
--- a/packages/server/src/mcp/tools/history.test.ts
+++ b/packages/server/src/mcp/tools/history.test.ts
@@ -52,6 +52,7 @@ let baseUrl: string;
beforeAll(() => {
testServer = Bun.serve({
port: 0,
+ hostname: '127.0.0.1',
fetch(req) {
const url = new URL(req.url);
if (url.pathname === '/api/history') {
@@ -74,7 +75,7 @@ beforeAll(() => {
return new Response('Not found', { status: 404 });
},
});
- baseUrl = `http://localhost:${testServer.port}`;
+ baseUrl = `http://127.0.0.1:${testServer.port}`;
});
afterAll(() => {
diff --git a/packages/server/src/mcp/tools/links.test.ts b/packages/server/src/mcp/tools/links.test.ts
index b6a4e49ed..e0f8d8379 100644
--- a/packages/server/src/mcp/tools/links.test.ts
+++ b/packages/server/src/mcp/tools/links.test.ts
@@ -84,6 +84,7 @@ const seenRequests: string[] = [];
beforeAll(() => {
testServer = Bun.serve({
port: 0,
+ hostname: '127.0.0.1',
fetch(req) {
const url = new URL(req.url);
seenRequests.push(`${url.pathname}?${url.searchParams.toString()}`);
@@ -154,7 +155,7 @@ beforeAll(() => {
}
},
});
- baseUrl = `http://localhost:${testServer.port}`;
+ baseUrl = `http://127.0.0.1:${testServer.port}`;
});
afterAll(() => {
diff --git a/packages/server/src/mcp/tools/restore-version.test.ts b/packages/server/src/mcp/tools/restore-version.test.ts
index f74d63a9d..8845f1ba0 100644
--- a/packages/server/src/mcp/tools/restore-version.test.ts
+++ b/packages/server/src/mcp/tools/restore-version.test.ts
@@ -65,6 +65,7 @@ let mockRollbackWarning: Record<string, unknown> | undefined;
beforeAll(() => {
testServer = Bun.serve({
port: 0,
+ hostname: '127.0.0.1',
async fetch(req) {
const url = new URL(req.url);
const body = req.method === 'POST' ? ((await req.json()) as Record<string, unknown>) : {};
@@ -84,7 +85,7 @@ beforeAll(() => {
return new Response('Not found', { status: 404 });
},
});
- baseUrl = `http://localhost:${testServer.port}`;
+ baseUrl = `http://127.0.0.1:${testServer.port}`;
});
afterAll(() => testServer.stop());
beforeEach(async () => {
diff --git a/packages/server/src/mcp/tools/share-link.test.ts b/packages/server/src/mcp/tools/share-link.test.ts
index 82244597f..fb39fd0e9 100644
--- a/packages/server/src/mcp/tools/share-link.test.ts
+++ b/packages/server/src/mcp/tools/share-link.test.ts
@@ -69,6 +69,7 @@ let mockRawResponse: Response | null = null;
beforeAll(() => {
testServer = Bun.serve({
port: 0,
+ hostname: '127.0.0.1',
async fetch(req) {
const url = new URL(req.url);
const body = req.method === 'POST' ? ((await req.json()) as Record<string, unknown>) : {};
@@ -83,7 +84,7 @@ beforeAll(() => {
return new Response('Not found', { status: 404 });
},
});
- baseUrl = `http://localhost:${testServer.port}`;
+ baseUrl = `http://127.0.0.1:${testServer.port}`;
});
afterAll(() => {
diff --git a/packages/server/src/mcp/tools/shared.test.ts b/packages/server/src/mcp/tools/shared.test.ts
index 40155e84a..dd08cf9b6 100644
--- a/packages/server/src/mcp/tools/shared.test.ts
+++ b/packages/server/src/mcp/tools/shared.test.ts
@@ -313,6 +313,7 @@ let baseUrl: string;
beforeAll(() => {
testServer = Bun.serve({
port: 0, // random available port
+ hostname: '127.0.0.1',
fetch(req) {
const url = new URL(req.url);
@@ -395,7 +396,7 @@ beforeAll(() => {
return new Response('Not found', { status: 404 });
},
});
- baseUrl = `http://localhost:${testServer.port}`;
+ baseUrl = `http://127.0.0.1:${testServer.port}`;
});
afterAll(() => {
@@ -538,10 +539,11 @@ describe('normalizeResponse — RFC 9457 + flat success', () => {
test('non-RFC-9457 5xx with no error/message → generic HTTP-status sentence', async () => {
const stripeServer = Bun.serve({
port: 0,
+ hostname: '127.0.0.1',
fetch: () => Response.json({ unrelated: true }, { status: 503 }),
});
try {
- const result = await httpGet(`http://localhost:${stripeServer.port}`, '/anything');
+ const result = await httpGet(`http://127.0.0.1:${stripeServer.port}`, '/anything');
expect(result.ok).toBe(false);
expect(result.error).toBe('Server returned HTTP 503');
expect(result.unrelated).toBe(true);
@@ -553,10 +555,11 @@ describe('normalizeResponse — RFC 9457 + flat success', () => {
test('non-RFC-9457 4xx with body.error string → `error` ← body.error', async () => {
const stubServer = Bun.serve({
port: 0,
+ hostname: '127.0.0.1',
fetch: () => Response.json({ error: 'rate limited', message: 'try again' }, { status: 429 }),
});
try {
- const result = await httpGet(`http://localhost:${stubServer.port}`, '/anything');
+ const result = await httpGet(`http://127.0.0.1:${stubServer.port}`, '/anything');
expect(result.ok).toBe(false);
expect(result.error).toBe('rate limited');
} finally {
diff --git a/packages/server/src/mcp/tools/summary-passthrough.test.ts b/packages/server/src/mcp/tools/summary-passthrough.test.ts
index f5986d094..8a6e9cafb 100644
--- a/packages/server/src/mcp/tools/summary-passthrough.test.ts
+++ b/packages/server/src/mcp/tools/summary-passthrough.test.ts
@@ -78,6 +78,7 @@ let tmpDir: string;
beforeAll(() => {
testServer = Bun.serve({
port: 0,
+ hostname: '127.0.0.1',
async fetch(req) {
const url = new URL(req.url);
if (req.method === 'GET') {
@@ -100,7 +101,7 @@ beforeAll(() => {
});
},
});
- baseUrl = `http://localhost:${testServer.port}`;
+ baseUrl = `http://127.0.0.1:${testServer.port}`;
});
afterAll(() => {
diff --git a/packages/server/src/rig-loopback-exclusivity.test.ts b/packages/server/src/rig-loopback-exclusivity.test.ts
new file mode 100644
index 000000000..077e940ad
--- /dev/null
+++ b/packages/server/src/rig-loopback-exclusivity.test.ts
@@ -0,0 +1,115 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import { createServer, type RequestListener, type Server } from 'node:http';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
+
+interface RigSeam {
+ server: Server;
+ port: number;
+ baseUrl: string;
+}
+
+async function bootRigSeam(handler: RequestListener): Promise<RigSeam> {
+ const server = createServer(handler);
+ const { port, baseUrl } = await listenOnLoopback(server);
+ return { server, port, baseUrl };
+}
+
+interface ForeignMarker {
+ host: string;
+ close: () => Promise<void>;
+}
+
+function tryBindForeignMarker(
+ host: '127.0.0.1' | '::1',
+ port: number,
+ markerToken: string,
+): Promise<ForeignMarker | 'rig-owned' | 'family-unavailable'> {
+ return new Promise((resolve, reject) => {
+ const s = createServer((_req, res) => {
+ res.writeHead(200, {
+ 'content-type': 'application/json',
+ 'x-foreign-marker': markerToken,
+ });
+ res.end(JSON.stringify({ foreignMarker: markerToken, answeredOn: host }));
+ });
+ s.on('error', (err: NodeJS.ErrnoException) => {
+ if (err.code === 'EADDRINUSE') resolve('rig-owned');
+ else if (err.code === 'EADDRNOTAVAIL' || err.code === 'EAFNOSUPPORT')
+ resolve('family-unavailable');
+ else reject(err);
+ });
+ s.listen(port, host === '::1' ? '::1' : '127.0.0.1', () => {
+ resolve({
+ host,
+ close: () => new Promise<void>((r) => s.close(() => r())),
+ });
+ });
+ });
+}
+
+function dialedLoopbackAddresses(baseUrl: string): Array<'127.0.0.1' | '::1'> {
+ const hostname = new URL(baseUrl).hostname;
+ if (hostname === 'localhost') return ['127.0.0.1', '::1'];
+ if (hostname === '127.0.0.1') return ['127.0.0.1'];
+ if (hostname === '::1' || hostname === '[::1]') return ['::1'];
+ throw new Error(`rig advertises a non-loopback dial host: ${hostname}`);
+}
+
+describe('rig loopback exclusivity', () => {
+ const cleanups: Array<() => Promise<void>> = [];
+ afterEach(async () => {
+ const errors: unknown[] = [];
+ while (cleanups.length > 0) {
+ const fn = cleanups.pop();
+ if (!fn) continue;
+ try {
+ await fn();
+ } catch (err) {
+ errors.push(err);
+ }
+ }
+ if (errors.length > 0)
+ throw new AggregateError(errors, 'rig-loopback-exclusivity cleanup failed');
+ });
+
+ test('client dial reaches the rig even when a foreign loopback-specific listener squats the rig port', async () => {
+ const rigToken = randomUUID();
+ const { server, port, baseUrl } = await bootRigSeam((_req, res) => {
+ res.writeHead(200, { 'content-type': 'application/json' });
+ res.end(JSON.stringify({ rigToken }));
+ });
+ cleanups.push(() => new Promise<void>((r) => server.close(() => r())));
+
+ const markerToken = `foreign-${randomUUID()}`;
+ for (const host of ['127.0.0.1', '::1'] as const) {
+ const marker = await tryBindForeignMarker(host, port, markerToken);
+ if (typeof marker === 'object') cleanups.push(marker.close);
+ }
+
+ const res = await fetch(`${baseUrl}/whoami`);
+ const body = (await res.json()) as Record<string, unknown>;
+
+ expect(res.headers.get('x-foreign-marker')).toBeNull();
+ expect(body).toEqual({ rigToken });
+ });
+
+ test('rig exclusively owns every loopback address its client URL can resolve to', async () => {
+ const { server, port, baseUrl } = await bootRigSeam((_req, res) => {
+ res.end('ok');
+ });
+ cleanups.push(() => new Promise<void>((r) => server.close(() => r())));
+
+ const squattable: string[] = [];
+ for (const host of dialedLoopbackAddresses(baseUrl)) {
+ const marker = await tryBindForeignMarker(host, port, 'exclusivity-probe');
+ if (marker === 'family-unavailable') continue;
+ if (typeof marker === 'object') {
+ squattable.push(host);
+ cleanups.push(marker.close);
+ }
+ }
+
+ expect(squattable).toEqual([]);
+ });
+});
diff --git a/packages/server/src/share/construct-url.test.ts b/packages/server/src/share/construct-url.test.ts
index 04a23a94a..e210969b9 100644
--- a/packages/server/src/share/construct-url.test.ts
+++ b/packages/server/src/share/construct-url.test.ts
@@ -298,7 +298,7 @@ describe('POST /api/share/construct-url', () => {
branchesOnOrigin: ['main'],
});
});
- const res = await fetch(`http://localhost:${rig.port}/api/share/construct-url`);
+ const res = await fetch(`http://127.0.0.1:${rig.port}/api/share/construct-url`);
expect(res.status).toBe(405);
});
diff --git a/packages/server/src/share/publish.integration.test.ts b/packages/server/src/share/publish.integration.test.ts
index 7c9f930a1..5ceb7c634 100644
--- a/packages/server/src/share/publish.integration.test.ts
+++ b/packages/server/src/share/publish.integration.test.ts
@@ -4,6 +4,7 @@ import { mkdtemp, rm } from 'node:fs/promises';
import type { Server } from 'node:http';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
+import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';
import type { SyncEngine } from '../sync-engine.ts';
function makeFakeSyncEngine(): { engine: SyncEngine; refreshRemoteCalls: () => number } {
@@ -21,6 +22,7 @@ function makeFakeSyncEngine(): { engine: SyncEngine; refreshRemoteCalls: () => n
interface TestRig {
port: number;
+ baseUrl: string;
projectDir: string;
server: Server;
cleanup: () => Promise<void>;
@@ -72,15 +74,11 @@ async function bootRig(options: RigOptions): Promise<TestRig> {
});
hocuspocus.configuration.extensions.push(ext);
- const port = await new Promise<number>((resolveListen) => {
- server.listen(0, () => {
- const addr = server.address();
- resolveListen(typeof addr === 'object' && addr ? addr.port : 0);
- });
- });
+ const { port, baseUrl } = await listenOnLoopback(server);
return {
port,
+ baseUrl,
projectDir,
server,
cleanup: async () => {
@@ -91,7 +89,7 @@ async function bootRig(options: RigOptions): Promise<TestRig> {
}
async function getJson(port: number, path: string): Promise<{ status: number; body: unknown }> {
- const res = await fetch(`http://localhost:${port}${path}`);
+ const res = await fetch(`http://127.0.0.1:${port}${path}`);
return { status: res.status, body: await res.json() };
}
@@ -100,7 +98,7 @@ async function postJson(
path: string,
body: unknown,
): Promise<{ status: number; body: unknown }> {
- const res = await fetch(`http://localhost:${port}${path}`, {
+ const res = await fetch(`http://127.0.0.1:${port}${path}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(body),
@@ -157,7 +155,7 @@ describe('GET /api/share/publish/owners', () => {
test('rejects POST with 405', async () => {
rig = await bootRig({ cliArgs: fixtureCliArgs('{}') });
- const res = await fetch(`http://localhost:${rig.port}/api/share/publish/owners`, {
+ const res = await fetch(`${rig.baseUrl}/api/share/publish/owners`, {
method: 'POST',
});
expect(res.status).toBe(405);
@@ -202,9 +200,7 @@ describe('GET /api/share/publish/name-check', () => {
`process.stderr.write("FIXTURE INVOKED — should not happen for invalid owner");process.exit(99);`,
],
});
- const res = await fetch(
- `http://localhost:${rig.port}/api/share/publish/name-check?owner=-bad&name=foo`,
- );
+ const res = await fetch(`${rig.baseUrl}/api/share/publish/name-check?owner=-bad&name=foo`);
expect(res.status).toBe(400);
});
@@ -213,7 +209,7 @@ describe('GET /api/share/publish/name-check', () => {
cliArgs: [process.execPath, '-e', `process.exit(99);`],
});
const res = await fetch(
- `http://localhost:${rig.port}/api/share/publish/name-check?owner=alice&name=with%2Fslash`,
+ `${rig.baseUrl}/api/share/publish/name-check?owner=alice&name=with%2Fslash`,
);
expect(res.status).toBe(400);
});
@@ -322,7 +318,7 @@ describe('POST /api/share/publish', () => {
rig = await bootRig({
cliArgs: [process.execPath, '-e', `process.exit(99);`],
});
- const res = await fetch(`http://localhost:${rig.port}/api/share/publish`, {
+ const res = await fetch(`${rig.baseUrl}/api/share/publish`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ owner: 'alice', name: 'demo', visibility: 'lobster' }),
@@ -334,7 +330,7 @@ describe('POST /api/share/publish', () => {
rig = await bootRig({
cliArgs: [process.execPath, '-e', `process.exit(99);`],
});
- const res = await fetch(`http://localhost:${rig.port}/api/share/publish`, {
+ const res = await fetch(`${rig.baseUrl}/api/share/publish`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ owner: 'alice', name: 'with space', visibility: 'private' }),
@@ -344,7 +340,7 @@ describe('POST /api/share/publish', () => {
test('GET method rejected with 405', async () => {
rig = await bootRig({ cliArgs: fixtureCliArgs('{}') });
- const res = await fetch(`http://localhost:${rig.port}/api/share/publish`);
+ const res = await fetch(`${rig.baseUrl}/api/share/publish`);
expect(res.status).toBe(405);
});