Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): block non-loopback fetch in unit tests, fix 4 real reaches (#4103)
Nick Gomez665973638b31
diff --git a/.changeset/hermetic-unit-test-network-guard.md b/.changeset/hermetic-unit-test-network-guard.mdnew file mode 100644index 000000000..2c1081fe9--- /dev/null+++ b/.changeset/hermetic-unit-test-network-guard.md@@ -0,0 +1,13 @@+---+---++No release. This branch is test infrastructure: a shared vitest setup file that+refuses non-loopback `fetch`, a contract test that imports every vitest project+and checks its resolved `setupFiles`, and the test-side fixes for the reaches the+guard exposed.++The one production edit is additive and inert by default. `ServerOptions` and+`BootServerOptions` gain an optional `acpRegistryFetchImpl`, forwarded to+`AcpRegistry`, which already accepted a `fetchImpl` and defaults to global+`fetch`. With the option unset every code path is byte-identical to before, so+there is no user-visible behaviour to describe in a release note.diff --git a/packages/app/src/components/HelpPopover.dom.test.tsx b/packages/app/src/components/HelpPopover.dom.test.tsxindex b5a79ed35..995c00d87 100644--- a/packages/app/src/components/HelpPopover.dom.test.tsx+++ b/packages/app/src/components/HelpPopover.dom.test.tsx@@ -14,6 +14,11 @@ vi.doMock('@lingui/react/macro', () => ({useLingui: () => ({ t: renderLinguiTemplate }),}));+vi.doMock('@inkeep/open-knowledge-core', async (importActual) => ({+ ...(await importActual<typeof import('@inkeep/open-knowledge-core')>()),+ getGitHubStars: async () => 1234,+}));+vi.doMock('@/lib/external-link', () => ({dispatchExternalLinkClick: () => {},}));@@ -50,24 +55,9 @@ function linkShape(link: HTMLElement) {};}-const originalFetch = globalThis.fetch;+afterEach(cleanup);describe('HelpPopover runtime behavior', () => {- beforeEach(() => {- globalThis.fetch = vi.fn(- async () =>- new Response(JSON.stringify({ stargazers_count: 1234 }), {- status: 200,- headers: { 'content-type': 'application/json' },- }),- ) as typeof globalThis.fetch;- });-- afterEach(() => {- cleanup();- globalThis.fetch = originalFetch;- });-test('exports the component', async () => {const mod = await import('./HelpPopover');expect(typeof mod.HelpPopover).toBe('function');@@ -179,7 +169,6 @@ describe('HelpPopover with the desktop bridge present', () => {});afterEach(() => {- cleanup();(window as unknown as { okDesktop?: unknown }).okDesktop = undefined;});diff --git a/packages/app/src/editor/components/EmojiInsertPopover.dom.test.tsx b/packages/app/src/editor/components/EmojiInsertPopover.dom.test.tsxindex 777e67b30..7392163ce 100644--- a/packages/app/src/editor/components/EmojiInsertPopover.dom.test.tsx+++ b/packages/app/src/editor/components/EmojiInsertPopover.dom.test.tsx@@ -1,10 +1,12 @@import { cleanup, render, screen, waitFor } from '@testing-library/react';import { Editor } from '@tiptap/core';-import { afterEach, describe, expect, test } from 'vitest';+import { afterEach, describe, expect, test, vi } from 'vitest';import { sharedExtensions } from '../extensions/shared';import { openEmojiPickerForEditor } from '../slash-command/emoji-picker-event';import { EmojiInsertPopover, insertEmojiAtCaret } from './EmojiInsertPopover';+vi.mock('@/components/emoji-picker', () => ({ FrimousseEmojiPicker: () => null }));+function mountEditor(): { editor: Editor; container: HTMLDivElement } {const container = document.createElement('div');document.body.appendChild(container);diff --git a/packages/app/vitest.config.ts b/packages/app/vitest.config.tsindex 7f3a4722a..cff8bde57 100644--- a/packages/app/vitest.config.ts+++ b/packages/app/vitest.config.ts@@ -1,7 +1,7 @@import { fileURLToPath } from 'node:url';import react from '@vitejs/plugin-react';import { defineConfig, type ViteUserConfig } from 'vitest/config';-import { bunGlobalShimPath, okVitestBase } from '../../test-support/vitest.base';+import { okVitestBase } from '../../test-support/vitest.base';import { RENDERER_DEDUPE } from './vite.dedupe';// `@lingui/{react,core}/macro` only run under the build's Babel macro pass; a@@ -40,7 +40,7 @@ export const appVitestConfig = {},test: {...okVitestBase.test,- setupFiles: [bunGlobalShimPath, idbPreloadPath],+ setupFiles: [...okVitestBase.test.setupFiles, idbPreloadPath],},} satisfies ViteUserConfig;diff --git a/packages/core/src/config/loopback-parity.test.ts b/packages/core/src/config/loopback-parity.test.tsnew file mode 100644index 000000000..3cf657511--- /dev/null+++ b/packages/core/src/config/loopback-parity.test.ts@@ -0,0 +1,37 @@+import { describe, expect, test } from 'vitest';+import { isLoopbackHostname } from '../../../../test-support/no-net-connect.ts';+import { isLoopbackBindAddress } from './resolve-server-config.ts';++const NAMED = ['localhost', '::1', '[::1]', '0.0.0.0', '::', 'example.com', 'notlocalhost'];+const OCTETS = [0, 1, 9, 10, 99, 100, 127, 128, 199, 200, 249, 250, 255, 256, 300, 999];++function octetCorpus(): string[] {+ const hosts: string[] = [];+ for (let position = 0; position < 4; position += 1) {+ for (const octet of OCTETS) {+ const parts = ['127', '0', '0', '1'];+ parts[position] = String(octet);+ hosts.push(parts.join('.'));+ }+ }+ return hosts;+}++describe('loopback predicate parity with the hermetic-test guard', () => {+ test('agrees with the core bind-address predicate across the octet corpus', () => {+ for (const host of [...NAMED, ...octetCorpus()]) {+ expect(isLoopbackHostname(host), host).toBe(isLoopbackBindAddress(host));+ }+ });++ test('these divergences from core are deliberate', () => {+ expect(isLoopbackHostname('app.localhost')).toBe(true);+ expect(isLoopbackBindAddress('app.localhost')).toBe(false);++ expect(isLoopbackHostname(' localhost ')).toBe(false);+ expect(isLoopbackBindAddress(' localhost ')).toBe(true);++ expect(isLoopbackHostname('[127.0.0.1]')).toBe(true);+ expect(isLoopbackBindAddress('[127.0.0.1]')).toBe(false);+ });+});diff --git a/packages/core/src/utils/github-stars.test.ts b/packages/core/src/utils/github-stars.test.tsnew file mode 100644index 000000000..8e9d7a41b--- /dev/null+++ b/packages/core/src/utils/github-stars.test.ts@@ -0,0 +1,111 @@+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';+import { getGitHubStars } from './github-stars.ts';++const guardedFetch = globalThis.fetch;++let answer: () => Promise<Response>;+let requested: Request[] = [];+let inits: (RequestInit | undefined)[] = [];++beforeEach(() => {+ requested = [];+ inits = [];+ globalThis.fetch = (async (input, init) => {+ const request = new Request(input as RequestInfo, init);+ if (new URL(request.url).host !== 'api.github.com') return guardedFetch(input, init);+ requested.push(request);+ inits.push(init);+ return answer();+ }) as typeof globalThis.fetch;+});++afterEach(() => {+ globalThis.fetch = guardedFetch;+});++async function warnsWhileRunning<T>(run: () => Promise<T>): Promise<T> {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ try {+ const outcome = await run();+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('[github-stars]'));+ return outcome;+ } finally {+ warn.mockRestore();+ }+}++function json(body: unknown, status = 200): Promise<Response> {+ return Promise.resolve(+ new Response(JSON.stringify(body), {+ status,+ headers: { 'content-type': 'application/json' },+ }),+ );+}++describe('getGitHubStars', () => {+ test('returns the star count and asks the repo endpoint for JSON', async () => {+ answer = () => json({ stargazers_count: 1234 });++ expect(await getGitHubStars()).toBe(1234);++ const request = requested[0];+ if (request === undefined) throw new Error('no request was made');+ expect(new URL(request.url).pathname).toBe('/repos/inkeep/open-knowledge');+ expect(request.headers.get('accept')).toBe('application/vnd.github+json');+ expect(request.headers.get('user-agent')).toBe('openknowledge.ai');+ });++ test('forwards caller init keys other than signal, which is how the docs layout gets ISR', async () => {+ answer = () => json({ stargazers_count: 1234 });++ await getGitHubStars({ next: { revalidate: 3600 } } as RequestInit);++ expect(inits).toHaveLength(1);+ expect((inits[0] as { next?: unknown } | undefined)?.next).toEqual({ revalidate: 3600 });+ });++ test('returns null when the response is not ok, even though the body would parse', async () => {+ answer = () => json({ stargazers_count: 1234 }, 403);++ expect(await warnsWhileRunning(() => getGitHubStars())).toBeNull();+ expect(requested).toHaveLength(1);+ });++ test('returns null when the payload omits stargazers_count', async () => {+ answer = () => json({ full_name: 'inkeep/open-knowledge' });++ expect(await getGitHubStars()).toBeNull();+ expect(requested).toHaveLength(1);+ });++ test('returns null when stargazers_count is present but not a number', async () => {+ answer = () => json({ stargazers_count: '1234' });++ expect(await getGitHubStars()).toBeNull();+ expect(requested).toHaveLength(1);+ });++ test('returns null when the transport fails', async () => {+ answer = () => Promise.reject(new TypeError('fetch failed'));++ expect(await warnsWhileRunning(() => getGitHubStars())).toBeNull();+ expect(requested).toHaveLength(1);+ });++ test('aborts with the caller signal, and the caller signal alone ends it', async () => {+ const controller = new AbortController();+ answer = () =>+ new Promise((_resolve, reject) => {+ controller.signal.addEventListener('abort', () => reject(new Error('aborted')));+ });++ const pending = warnsWhileRunning(() => getGitHubStars({ signal: controller.signal }));+ controller.abort();+ expect(await pending).toBeNull();++ const forwarded = requested[0]?.signal;+ expect(forwarded?.aborted).toBe(true);+ expect((forwarded?.reason as { name?: string } | undefined)?.name).toBe('AbortError');+ });+});diff --git a/packages/desktop/src/main/ipc/bug-report.test.ts b/packages/desktop/src/main/ipc/bug-report.test.tsindex f7c31d731..2c053a1f6 100644--- a/packages/desktop/src/main/ipc/bug-report.test.ts+++ b/packages/desktop/src/main/ipc/bug-report.test.ts@@ -16,6 +16,10 @@ import { createServer, type Server } from 'node:http';import { tmpdir } from 'node:os';import { basename, dirname, join, resolve } from 'node:path';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';+import {+ REFUSED_LOOPBACK_ORIGIN,+ REFUSED_LOOPBACK_ORIGIN_ALT,+} from '../../../../../test-support/refused-loopback.test-helper.ts';const startedSpanNames: string[] = [];vi.mock('@inkeep/open-knowledge-server', async (importOriginal) => {@@ -2674,7 +2678,7 @@ describe('bug-report sidecar wiring — create writes the record, send tracks stconst result = await handleBugReportSend({- ...makeSendDeps('https://intake.invalid-tld-for-test.invalid', dir),+ ...makeSendDeps(REFUSED_LOOPBACK_ORIGIN, dir),sidecar: store.sendHooks,},{ kind: 'send', zipPath, metadata: SEND_METADATA },@@ -2684,12 +2688,12 @@ describe('bug-report sidecar wiring — create writes the record, send tracks stconst sidecar = await readSidecarValue(sidecarPathForId(dir, REPORT_ID));expect(sidecar?.lastError).toMatchObject({reason: 'mint-network-error',- errorCode: 'ENOTFOUND',+ errorCode: 'ECONNREFUSED',});expect(sidecar?.attempts?.at(-1)).toMatchObject({outcome: 'failed',error: 'mint-network-error',- errorCode: 'ENOTFOUND',+ errorCode: 'ECONNREFUSED',});expect(JSON.stringify(sidecar)).not.toContain('fetch failed');});@@ -2771,8 +2775,8 @@ describe('handleBugReportSend — structured failure diagnostics', () => {return line;}- test('an unresolvable intake names the step, the errno, and the host', async () => {- const { deps, zipPath } = makeSendRig('https://intake.invalid-tld-for-test.invalid');+ test('an unreachable intake names the step, the errno, and the host', async () => {+ const { deps, zipPath } = makeSendRig(REFUSED_LOOPBACK_ORIGIN);const lines = await captureIpcErrors(() =>handleBugReportSend(deps, { kind: 'send', zipPath, metadata: SEND_METADATA }),@@ -2780,16 +2784,17 @@ describe('handleBugReportSend — structured failure diagnostics', () => {const details = dispatchFailure(lines).details as Record<string, unknown>;expect(details.step).toBe('mint');- expect(details.host).toBe('intake.invalid-tld-for-test.invalid');+ expect(details.host).toBe(new URL(REFUSED_LOOPBACK_ORIGIN).host);expect(details.errName).toBe('TypeError');- expect(details.errCode).toBe('ENOTFOUND');+ expect(details.errCode).toBe('ECONNREFUSED');});test('a failing upload names the storage host without leaking the signature', async () => {+ const storageOrigin = REFUSED_LOOPBACK_ORIGIN;const stub = await startIntakeStub({mintBody: {- uploadUrl: 'https://storage.example.invalid/dest?X-Signature=SUPERSECRETSIG&exp=99',- assetUrl: 'https://uploads.example.invalid/asset/dest',+ uploadUrl: `${storageOrigin}/dest?X-Signature=SUPERSECRETSIG&exp=99`,+ assetUrl: `${REFUSED_LOOPBACK_ORIGIN_ALT}/asset/dest`,headers: {},},});@@ -2802,7 +2807,7 @@ describe('handleBugReportSend — structured failure diagnostics', () => {const line = dispatchFailure(lines);const details = line.details as Record<string, unknown>;expect(details.step).toBe('upload');- expect(details.host).toBe('storage.example.invalid');+ expect(details.host).toBe(new URL(storageOrigin).host);expect(JSON.stringify(line)).not.toContain('SUPERSECRETSIG');});@@ -2819,7 +2824,7 @@ describe('handleBugReportSend — structured failure diagnostics', () => {});test('a transport throw names its leg in the reason, not just in the details', async () => {- const { deps, zipPath } = makeSendRig('https://intake.invalid-tld-for-test.invalid');+ const { deps, zipPath } = makeSendRig(REFUSED_LOOPBACK_ORIGIN);const lines = await captureIpcErrors(() =>handleBugReportSend(deps, { kind: 'send', zipPath, metadata: SEND_METADATA }),diff --git a/packages/server/src/api-config-system-composition.test.ts b/packages/server/src/api-config-system-composition.test.tsindex c9be74466..d26aaedfe 100644--- a/packages/server/src/api-config-system-composition.test.ts+++ b/packages/server/src/api-config-system-composition.test.ts@@ -89,11 +89,21 @@ const ALL_ROUTES = [...READ_200, '/api/acp/catalog', '/api/installed-agents', '/let tmpRoot: string;let server: BootedServer;+const acpRegistryRequests: string[] = [];++const acpRegistryFetchImpl = (async (input: Parameters<typeof fetch>[0]) => {+ acpRegistryRequests.push(new Request(input as RequestInfo).url);+ return new Response('{"agents":[]}', {+ status: 200,+ headers: { 'content-type': 'application/json' },+ });+}) as typeof fetch;+beforeAll(async () => {tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-config-system-native-'));const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');- server = await bootCompositionRig(contentDir);+ server = await bootCompositionRig(contentDir, { acpRegistryFetchImpl });await server.ready;}, 60_000);@@ -130,9 +140,12 @@ describe('config-system group over the composed listener — served natively', (}});- test('acp/catalog serves natively without depending on live CDN egress (200 or 502)', async () => {+ test('acp/catalog serves natively against a stubbed registry (200, no live CDN egress)', async () => {const res = await fetch(`http://127.0.0.1:${server.port}/api/acp/catalog`);- expect([200, 502]).toContain(res.status);+ expect(res.status).toBe(200);+ expect(acpRegistryRequests).toEqual([+ 'https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json',+ ]);});test('principal serves natively behind its inline gate (200 when resolvable, else its own 404)', async () => {diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.tsindex b2d6aeb9d..a8ba64adf 100644--- a/packages/server/src/boot.ts+++ b/packages/server/src/boot.ts@@ -179,6 +179,7 @@ export interface BootServerOptions| 'singleDocRelPath'| 'ephemeral'| 'configHomedirOverride'+ | 'acpRegistryFetchImpl'> {config: Config;skipAutoInit?: boolean;@@ -405,6 +406,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {const serverInstance = createServer({getCollabClientCount: () => collabClientCounter?.getCount() ?? 0,+ acpRegistryFetchImpl: opts.acpRegistryFetchImpl,contentDir: opts.contentDir,projectDir: opts.projectDir,ingressPolicy,diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex adfcd440b..b784ad8b6 100644--- a/packages/server/src/server-factory.ts+++ b/packages/server/src/server-factory.ts@@ -265,6 +265,7 @@ import { trustSystemCertificates } from './trust-system-ca.ts';import { cleanupOrphanUploadTempfiles } from './upload-streaming.ts';export interface ServerOptions {+ acpRegistryFetchImpl?: typeof fetch;ingressPolicy?: IngressPolicy;port?: number;host?: string;@@ -698,7 +699,11 @@ export function createServer(options: ServerOptions): ServerInstance {const lockDir = getLocalDir(projectDir);- const acpRegistry = new AcpRegistry({ localDir: lockDir, log: getLogger('acp-registry') });+ const acpRegistry = new AcpRegistry({+ localDir: lockDir,+ log: getLogger('acp-registry'),+ fetchImpl: options.acpRegistryFetchImpl,+ });const acpPermissions = new AcpPermissionStore(lockDir, getLogger('acp-permissions'));acquireServerLock(lockDir, {diff --git a/scripts/compute-next-beta.test.mjs b/scripts/compute-next-beta.test.mjsindex 8abdcf6df..f9ffd967e 100644--- a/scripts/compute-next-beta.test.mjs+++ b/scripts/compute-next-beta.test.mjs@@ -438,4 +438,8 @@ describe('parseFrontmatterBumpType', () => {test('returns null when there is no frontmatter', () => {expect(parseFrontmatterBumpType('no frontmatter here')).toBeNull();});++ test('returns null for an empty changeset, which declares no bump for any package', () => {+ expect(parseFrontmatterBumpType('---\n---\n\nNo release.\n')).toBeNull();+ });});diff --git a/test-support/no-net-connect.test.ts b/test-support/no-net-connect.test.tsnew file mode 100644index 000000000..48f0bfc74--- /dev/null+++ b/test-support/no-net-connect.test.ts@@ -0,0 +1,144 @@+import { createServer } from 'node:http';+import { describe, expect, test, vi } from 'vitest';+import { installNoNetConnect, isLoopbackHostname, NetConnectBlockedError } from './no-net-connect';+import {+ REFUSED_LOOPBACK_ORIGIN,+ REFUSED_LOOPBACK_ORIGIN_ALT,+} from './refused-loopback.test-helper';++// Port 1 is on the WHATWG fetch blocked-port list. It is named only here, as the+// alternative the refused origin must NOT drift into.+const FETCH_BLOCKED_PORT_ORIGIN = 'http://127.0.0.1:1';++describe('isLoopbackHostname', () => {+ test.each([+ 'localhost',+ 'LOCALHOST',+ '127.0.0.1',+ '127.1.2.3',+ '127.255.255.255',+ '::1',+ '[::1]',+ 'app.localhost',+ ])('%s is loopback', (host) => expect(isLoopbackHostname(host)).toBe(true));++ test.each([+ 'example.com',+ 'intake.invalid-tld-for-test.invalid',+ '127.0.0.1.evil.com',+ 'notlocalhost',+ '10.0.0.1',+ '169.254.169.254',+ '0.0.0.0',+ '::',+ '127.999.0.1',+ '127.0.0.256',+ ])('%s is not loopback', (host) => expect(isLoopbackHostname(host)).toBe(false));+});++// Only the tests that trip the guard ON PURPOSE mute it, and each of them asserts+// the `[no-net-connect]` line was emitted. Muting block-wide would swallow an+// UNEXPECTED console.error from the tests that are meant to stay silent, and+// muting without asserting would leave the log line -- the enforcement mechanism+// behind the zero-lines invariant -- as the one thing here with no coverage.+async function blockedBy(run: () => Promise<unknown>): Promise<unknown> {+ const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});+ try {+ const outcome = await run().catch((e: unknown) => e);+ expect(consoleError).toHaveBeenCalledWith(expect.stringContaining('[no-net-connect]'));+ return outcome;+ } finally {+ consoleError.mockRestore();+ }+}++describe('the installed fetch guard', () => {+ test('socketless schemes are allowed through without a host check', async () => {+ const res = await fetch('data:text/plain,hello');+ expect(await res.text()).toBe('hello');+ });++ test('installing twice is a no-op because the marker rides the wrapper', () => {+ const before = globalThis.fetch;+ installNoNetConnect();+ expect(globalThis.fetch).toBe(before);+ });++ test('reinstalling over an unmarked reassignment re-wraps rather than trusting a stale global', async () => {+ const guarded = globalThis.fetch;+ const unmarked = (async () => new Response('bypassed')) as typeof globalThis.fetch;+ globalThis.fetch = unmarked;+ try {+ installNoNetConnect();+ expect(globalThis.fetch).not.toBe(unmarked);+ const err = await blockedBy(() => fetch('https://example.com'));+ expect(err).toBeInstanceOf(NetConnectBlockedError);+ } finally {+ globalThis.fetch = guarded;+ }+ });++ test('rejects a non-loopback request and names the offending test', async () => {+ const err = (await blockedBy(() =>+ fetch('https://intake.invalid-tld-for-test.invalid/api/bug-report'),+ )) as Error;+ expect(err).toBeInstanceOf(NetConnectBlockedError);+ expect(err.message).toMatch(/intake\.invalid-tld-for-test\.invalid/);+ expect(err.message).toMatch(/names the offending test/);+ });++ test('carries no errno-shaped `code`, so it cannot masquerade as a real transport error', async () => {+ const err = await blockedBy(() => fetch('https://example.com'));+ expect(err).toBeInstanceOf(NetConnectBlockedError);+ expect((err as { code?: unknown }).code).toBeUndefined();+ expect((err as { cause?: unknown }).cause).toBeUndefined();+ });++ test('lets a real loopback server through untouched', async () => {+ const server = createServer((_req, res) => {+ res.writeHead(200, { 'content-type': 'text/plain' });+ res.end('reachable');+ });+ await new Promise<void>((done) => server.listen(0, '127.0.0.1', () => done()));+ const address = server.address();+ if (address === null || typeof address === 'string') throw new Error('no port');+ try {+ const res = await fetch(`http://127.0.0.1:${address.port}/`);+ expect(await res.text()).toBe('reachable');+ } finally {+ await new Promise<void>((done) => server.close(() => done()));+ }+ });++ test.each([+ REFUSED_LOOPBACK_ORIGIN,+ REFUSED_LOOPBACK_ORIGIN_ALT,+ ])('%s yields a real kernel-level transport error', async (origin) => {+ const err = (await fetch(`${origin}/api`).catch((e: unknown) => e)) as {+ name?: string;+ cause?: { code?: string; syscall?: string };+ };+ expect(err).not.toBeInstanceOf(NetConnectBlockedError);+ expect(err.name).toBe('TypeError');+ expect(err.cause?.code).toBe('ECONNREFUSED');+ expect(err.cause?.syscall).toBe('connect');+ });++ test.each([+ REFUSED_LOOPBACK_ORIGIN,+ REFUSED_LOOPBACK_ORIGIN_ALT,+ ])('%s sits below every ephemeral range, so listen(0) cannot hand it out', (origin) => {+ const port = Number(new URL(origin).port);+ expect(port).toBeGreaterThan(0);+ expect(port).toBeLessThan(32768);+ });++ test('a fetch-blocked port would NOT do: it fails with no errno at all', async () => {+ const err = (await fetch(`${FETCH_BLOCKED_PORT_ORIGIN}/api`).catch((e: unknown) => e)) as {+ name?: string;+ cause?: { code?: string };+ };+ expect(err.name).toBe('TypeError');+ expect(err.cause?.code).toBeUndefined();+ });+});diff --git a/test-support/no-net-connect.ts b/test-support/no-net-connect.tsnew file mode 100644index 000000000..b67cea83d--- /dev/null+++ b/test-support/no-net-connect.ts@@ -0,0 +1,141 @@+/**+ * Hermetic-test guard: rejects `fetch` to anything that is not loopback.+ *+ * A unit test whose pass/fail depends on a socket to the outside world inherits+ * the resolver, the proxy, and a remote host's availability. This makes that class+ * refuse before it leaves the process, naming the test that made the request.+ *+ * Loopback stays reachable deliberately: suites here stand up real servers on+ * 127.0.0.1 and talk to them, which never leaves the machine. A CLOSED loopback+ * port is the sanctioned way to get a REAL transport error without inventing one+ * (see `refused-loopback.test-helper.ts`).+ *+ * A clean run emits ZERO `[no-net-connect]` lines; the guard's own suite mutes its+ * deliberate blocks to keep that literally true. A guard that fires routinely is a+ * broken alarm, so a line in CI output is a new reach to fix at its seam.+ *+ * WHAT THIS DOES NOT COVER, in rough order of how likely you are to hit it:+ * - A test that assigns over `globalThis.fetch`. The guard is then inert in that+ * file, for every host. This is the dominant idiom in this subtree, so the file+ * you are editing may well have it switched off. Prefer a+ * host-conditional pass-through to the captured real fetch, or a module-level+ * fake, over a blanket replacement.+ * - `node:http` / `node:https` directly. `packages/server/src/link-preview/+ * guarded-fetch.ts` is shipping product code that does exactly this.+ * - Raw `node:net` sockets, and jsdom's `XMLHttpRequest`.+ * - Spawned subprocesses, which own their own globals: the CLI e2e tier+ * (`packages/cli/vitest.e2e.config.ts`) tests a binary in another process.+ *+ * Prior art, and why this diverges: `msw` (`setupServer(...).listen({+ * onUnhandledRequest: 'error' })`) closes `node:http`, XHR and `fetch` in one+ * interceptor stack; `nock` and undici's `MockAgent` both offer+ * `disableNetConnect` / `enableNetConnect`, and `MockAgent` intercepts at the+ * dispatcher rather than by replacing a global. All three are request-mocking+ * frameworks; what is wanted here is a single allow-loopback-only policy on the one+ * surface this code fetches through, installed in every worker with no per-test+ * registration. Note also that none of them closes the first gap above: a+ * `globalThis.fetch` reassignment bypasses a dispatcher just as completely.+ *+ * There is deliberately no opt-out flag: an escape hatch would be re-openable by+ * the next test that finds the guard inconvenient.+ */+import { expect } from 'vitest';++const INSTALLED = Symbol.for('ok.test.noNetConnect.installed');++// Deliberately matches `isLoopbackBindAddress` in packages/core+// (src/config/resolve-server-config.ts): same hosts, same octet validation. The+// wildcards `0.0.0.0` and `::` are NOT loopback -- core classifies them that way,+// `loopback-bind-discipline.test.ts` treats binding them as a violation, and per+// Winsock the all-zeros destination is not even routable on Windows. `.localhost`+// is admitted on top of core's set: RFC 6761 reserves it to resolve to loopback,+// and this predicate answers about fetch targets rather than bind addresses.+// Both halves of that claim, the parity and the deliberate divergences, are+// enforced by `packages/core/src/config/loopback-parity.test.ts`, which lives+// beside `isLoopbackBindAddress` because that is where its dep graph already is.+const IPV4_OCTET = '(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)';+const LOOPBACK_V4_RE = new RegExp(`^127\\.${IPV4_OCTET}\\.${IPV4_OCTET}\\.${IPV4_OCTET}$`);++const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);++export function isLoopbackHostname(hostname: string): boolean {+ const bare =+ hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;+ const lower = bare.toLowerCase();+ if (LOOPBACK_HOSTNAMES.has(lower)) return true;+ if (lower.endsWith('.localhost')) return true;+ return LOOPBACK_V4_RE.test(lower);+}++function resolveTarget(input: unknown): URL | null {+ const base =+ typeof globalThis.location?.href === 'string' ? globalThis.location.href : undefined;+ const raw =+ typeof input === 'string'+ ? input+ : input instanceof URL+ ? input.href+ : typeof (input as { url?: unknown })?.url === 'string'+ ? (input as { url: string }).url+ : null;+ if (raw === null) return null;+ try {+ return new URL(raw, base);+ } catch {+ return null;+ }+}++// data:/blob:/file: carry no host and open no socket, so a hostname test would+// refuse them for having an empty hostname rather than for going anywhere.+const SOCKETLESS_PROTOCOLS = new Set(['data:', 'blob:', 'file:']);++export class NetConnectBlockedError extends Error {+ override readonly name = 'NetConnectBlockedError' as const;+ constructor(hostname: string, testName: string) {+ super(+ `Blocked an outbound network request to "${hostname}" from test: ${testName}. ` ++ 'Unit tests must be hermetic — only loopback hosts are reachable. Fake the ' ++ 'dependency at its seam, or point it at a CLOSED loopback port when you need a ' ++ 'real transport error. See test-support/no-net-connect.ts.',+ );+ }+}++export function installNoNetConnect(): void {+ const realFetch = globalThis.fetch;+ if (typeof realFetch !== 'function') return;+ // The marker lives on the wrapper rather than on `globalThis`, so a test that+ // replaced `fetch` without restoring it cannot make a later install believe the+ // guard is present when it is not (precedent: `client-fetch.ts`).+ if ((realFetch as { [INSTALLED]?: boolean })[INSTALLED] === true) return;++ const guardedFetch = async function guardedFetch(+ input: Parameters<typeof realFetch>[0],+ init?: Parameters<typeof realFetch>[1],+ ): ReturnType<typeof realFetch> {+ const target = resolveTarget(input);+ // An unresolvable target cannot reach the network either way: `fetch` rejects a+ // malformed or relative-without-base URL before opening a socket, so passing it+ // through surfaces its own error rather than masking it with the guard's.+ if (+ target !== null &&+ !SOCKETLESS_PROTOCOLS.has(target.protocol) &&+ !isLoopbackHostname(target.hostname)+ ) {+ const testName = expect.getState().currentTestName ?? '<outside a test>';+ const blocked = new NetConnectBlockedError(target.hostname, testName);+ // A caller that swallows transport errors (every defensive upload path does)+ // would otherwise turn this into a silently-wrong assertion rather than a+ // legible failure, which is the exact invisibility this guard exists to end.+ console.error(`[no-net-connect] ${blocked.message}`);+ throw blocked;+ }+ return realFetch(input, init);+ } as typeof realFetch;++ (guardedFetch as { [INSTALLED]?: boolean })[INSTALLED] = true;+ globalThis.fetch = guardedFetch;+}++installNoNetConnect();diff --git a/test-support/refused-loopback.test-helper.ts b/test-support/refused-loopback.test-helper.tsnew file mode 100644index 000000000..f04e78018--- /dev/null+++ b/test-support/refused-loopback.test-helper.ts@@ -0,0 +1,27 @@+/**+ * Loopback origins whose connections are always refused by the kernel.+ *+ * A client pointed here gets a REAL transport failure rather than a hand-built+ * `Error`: nothing listens, so `fetch` rejects with a genuine undici+ * `TypeError: fetch failed` wrapping `Error { code: 'ECONNREFUSED', syscall:+ * 'connect' }`, and it never leaves the machine.+ *+ * Two constraints fix the port numbers, both pinned by `no-net-connect.test.ts`:+ *+ * - Below every platform's ephemeral range (Linux 32768-60999, macOS and Windows+ * 49152-65535), so `listen(0)` can never hand one out. Bind-then-close returns+ * the port to that pool, leaving a window for a concurrent test to re-bind it+ * and turn the expected refusal into a connection.+ * - Not on the WHATWG fetch blocked-port list. Port 1 is, and fails quietly+ * rather than loudly: fetch rejects before any syscall with+ * `cause: Error('bad port')`, which carries no `code`, so an errno assertion+ * reads `undefined` instead of `ECONNREFUSED`.+ *+ * The ALT origin exists so a test can tell two hosts apart: a "names the host it+ * actually tried" assertion stops discriminating once both candidates collapse+ * onto one origin. Both origins are held to both constraints by the same+ * parametrized tests, so neither can rot into the other's shape.+ */+export const REFUSED_LOOPBACK_ORIGIN = 'http://127.0.0.1:4';++export const REFUSED_LOOPBACK_ORIGIN_ALT = 'http://127.0.0.1:5';diff --git a/test-support/setup-files-contract.test.ts b/test-support/setup-files-contract.test.tsnew file mode 100644index 000000000..d2e43ebbe--- /dev/null+++ b/test-support/setup-files-contract.test.ts@@ -0,0 +1,207 @@+/**+ * Pins the real invariant: every vitest project resolves a `setupFiles` array+ * that contains the hermetic-network guard.+ *+ * This used to match config SOURCE TEXT for a derived spread, which is how the+ * guard could go missing: a project that writes its own `test: { ... }`, or its+ * own `setupFiles:` key, replaces the base array rather than extending it, and+ * every test still passes. Five rewrites of that heuristic each closed one+ * spelling and admitted the next — comment text vouching for code, a base spread+ * short-circuiting the key, an inert optional group, a name mention standing in+ * for the value, and finally `[...base.test.setupFiles].filter(...)`, which reads+ * as a derived spread and drops whatever the filter removes. A regex over source+ * text is modelling JS array semantics in a character class; it cannot converge.+ *+ * So the configs are imported and their RESOLVED arrays inspected instead. No+ * spelling can defeat that: spread, pass-through, index, `.filter`, `.concat` and+ * anything else all collapse to the array the project actually runs with.+ *+ * The earlier objection to importing them — that `packages/app/vitest.config.ts`+ * needs `@vitejs/plugin-react`, which the OK root does not depend on — does not+ * hold. Bare specifiers resolve from the importer's directory, and pnpm's+ * isolated layout puts a declared devDep at `packages/app/node_modules`, so the+ * import resolves from here. Verified by importing it from outside the package.+ *+ * Two assertions, because either alone has a blind spot. Each project's resolved+ * array is compared against `okVitestBase.test.setupFiles`, which needs no+ * maintenance when the base gains a guard but is self-referential: delete an entry+ * from the base and both sides move together. So the base is ALSO checked against+ * a literal list, which exists purely to be the fixed point the derived comparison+ * lacks. That list, `KNOWN_TEST_PROJECTS` and `KNOWN_BUILD_CONFIGS` are the three+ * things here anyone has to maintain by hand, and they are not all the same shape.+ * The two config lists are EXACT, so a config appearing or disappearing both fail;+ * a floor would have let a vanishing project pass silently, which is the direction+ * that matters. `REQUIRED_BASE_SETUP_FILES` is deliberately a subset check, since+ * the base gaining a guard should not red this file. What it does catch is a+ * project installing only SOME of the base's entries, which is the per-project+ * comparison's job: picking a single entry out of the base array fails there.+ *+ * `findConfigs` enumerates every config the repo TRACKS, so a NEW project is+ * covered the moment its config lands, with no per-project opt-in to forget.+ * Only vitest projects are imported: a build config like+ * `packages/app/vite.config.ts` mutates `process.env` and touches the filesystem at+ * module scope, so importing it to learn it has no `test` block would pay a real+ * side effect for a null result. They are enumerated in `KNOWN_BUILD_CONFIGS`+ * instead, so a new one forces a decision rather than being classified by a+ * pattern that fails open on an indirected `test` key and closed on a comment+ * containing one. The vitest configs pay their own import cost deliberately,+ * which is the price of reading resolved arrays rather than parsing text.+ * `docs/vitest.real-source.config.mts` is the only function-form one, so it is the+ * only config whose factory this file CALLS; that call runs+ * `mdx(..., { outDir: '.source-vitest' })` against this cwd rather than the docs+ * runner's, and a `git status --porcelain` after a full run measured clean. Nothing+ * pins that: `.source-vitest/` is ignored only under `docs/`, so if an upstream+ * change ever moved emission to call time the artifact would surface here as an+ * untracked OK-root directory. Nothing automated reads that: the signal is a+ * `git status` before the next commit, and a git ignore rule at OK root would+ * delete it, so none is added.+ */+import { execFileSync } from 'node:child_process';+import { existsSync } from 'node:fs';+import { basename, join } from 'node:path';+import { fileURLToPath, pathToFileURL } from 'node:url';+import { describe, expect, test } from 'vitest';+import { gitCleanEnv } from '../scripts/git-clean-env.mjs';+import { okVitestBase } from './vitest.base';++const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));++// Both patterns admit a dotted prefix, because the repo uses that form+// (`electron.vite.config.ts`). Start-anchoring them would hide a future+// `electron.vitest.config.ts` from the sweep entirely.+const CONFIG_FILENAME = /(?:^|\.)vite(st)?[\w.-]*\.config\.m?[jt]s$/;+const TEST_CONFIG_FILENAME = /(?:^|\.)vitest[\w.-]*\.config\.m?[jt]s$/;++// Every TRACKED config matching TEST_CONFIG_FILENAME, enumerated rather than+// counted, so a project disappearing fails as loudly as one appearing.+const KNOWN_TEST_PROJECTS = [+ 'docs/vitest.config.ts',+ 'docs/vitest.real-source.config.mts',+ 'packages/app/vitest.config.ts',+ 'packages/app/vitest.dom.config.ts',+ 'packages/app/vitest.fidelity.config.ts',+ 'packages/app/vitest.integration.config.ts',+ 'packages/cli/vitest.config.ts',+ 'packages/cli/vitest.e2e.config.ts',+ 'packages/core/vitest.config.ts',+ 'packages/desktop/vitest.config.ts',+ 'packages/md-conformance/md-audit/vitest.config.ts',+ 'packages/md-conformance/vitest.config.ts',+ 'packages/server/vitest.config.ts',+ 'vitest.config.ts',+ 'vitest.scripts.config.ts',+];++// Every config matching CONFIG_FILENAME that is NOT a vitest project.+const KNOWN_BUILD_CONFIGS = [+ 'packages/app/vite.config.ts',+ 'packages/desktop/electron.vite.config.ts',+];++// Named literally, NOT derived from the base. The per-project check compares+// against `okVitestBase.test.setupFiles`, which is self-referential on its own:+// delete an entry from the base and both sides move together, leaving the suite+// green with that guard uninstalled everywhere. This is the anchor that catches it.+const REQUIRED_BASE_SETUP_FILES = ['bun-global-shim.ts', 'no-net-connect.ts'];++const isTestConfig = (relPath: string): boolean => TEST_CONFIG_FILENAME.test(basename(relPath));++// TRACKED files, not a directory walk, and read through git rather than the+// filesystem. A PR check tests the branch MERGED with its base, so the working tree+// can lack a config the base has gained: `docs/vitest.real-source.config.mts`+// landed on main while this branch was behind it, and a disk sweep saw 14 projects+// here against CI's 15. `git ls-files` is the set the invariant is about, and it is+// the same set on a runner and in a worktree at the same commit.+//+// `ls-files` reads the INDEX, so a config staged-then-deleted from the working+// tree is still enumerated: a vitest one then fails on `import()` with a+// module-not-found naming a path that looks fine, and a build config fails+// nothing, because only vitest projects are imported. Neither is caught by the+// exact enumerations, because the index still lists the name. Filtering the sweep+// by `existsSync` would catch them there, but only by reintroducing the+// index-vs-disk skew rejected above, and the vitest half would red with a message+// telling the reader to edit `KNOWN_TEST_PROJECTS` when the fix is to restore the+// file. So it is asserted separately instead, which puts a named sentence ahead of+// the module-not-found.+//+// `gitCleanEnv()` because `execFileSync` inherits `process.env` and `cwd` does not+// override an inherited GIT_DIR, so any caller that already has one would resolve+// this `ls-files` against a different tree. The pre-push hook is NOT that caller —+// it unsets the GIT_* family before any step runs — so this is prophylaxis against+// a future caller, following `scripts/check-no-tracked-but-ignored.test.mjs`, not a+// fix for a live path.+function findConfigs(): string[] {+ return execFileSync(+ 'git',+ ['ls-files', '-z', '--', '*.config.ts', '*.config.mts', '*.config.js', '*.config.mjs'],+ {+ cwd: REPO_ROOT,+ env: gitCleanEnv(),+ encoding: 'utf8',+ },+ )+ .split('\0')+ .filter((relPath) => relPath !== '' && CONFIG_FILENAME.test(basename(relPath)))+ .sort();+}++async function resolveSetupFiles(relPath: string): Promise<string[]> {+ const loaded: unknown = await import(pathToFileURL(join(REPO_ROOT, relPath)).href);+ const exported = (loaded as { default?: unknown }).default ?? loaded;+ const config =+ typeof exported === 'function' ? await exported({ command: 'serve', mode: 'test' }) : exported;+ const setupFiles = (config as { test?: { setupFiles?: unknown } }).test?.setupFiles;+ if (setupFiles === undefined) return [];+ return (Array.isArray(setupFiles) ? setupFiles : [setupFiles]).map(String);+}++const configs = findConfigs();++describe('vitest setupFiles contract', () => {+ test('every tracked config is present in the working tree', () => {+ const missing = configs.filter((relPath) => !existsSync(join(REPO_ROOT, relPath)));+ expect(+ missing,+ `git lists these configs but they are absent from the working tree: ${missing.join(', ')}. ` ++ 'The sweep reads the index, so a vitest one fails below as module-not-found, and a ' ++ 'build config passes every other assertion here, because the index still lists it.',+ ).toEqual([]);+ });++ test('the shared base itself still installs every required setup file', () => {+ for (const required of REQUIRED_BASE_SETUP_FILES) {+ expect(+ okVitestBase.test.setupFiles.some((entry) => basename(entry) === required),+ `okVitestBase.test.setupFiles no longer installs ${required}, so every project ` ++ 'below would agree with a base that stopped installing it.',+ ).toBe(true);+ }+ });++ test('the sweep sees exactly the vitest projects the repo tracks', () => {+ expect(+ configs.filter(isTestConfig).sort(),+ 'A vitest project appeared or disappeared. Confirm the new one is covered, then update ' ++ 'this list; a lower bound would have let a disappearing project pass silently.',+ ).toEqual([...KNOWN_TEST_PROJECTS].sort());+ });++ test('every non-vitest config in the sweep is a known build config', () => {+ expect(configs.filter((relPath) => !isTestConfig(relPath)).sort()).toEqual(+ [...KNOWN_BUILD_CONFIGS].sort(),+ );+ });++ test.each(+ configs.filter(isTestConfig),+ )('%s resolves setupFiles containing every entry the shared base installs', async (relPath) => {+ const setupFiles = await resolveSetupFiles(relPath);+ const missing = okVitestBase.test.setupFiles.filter((entry) => !setupFiles.includes(entry));+ expect(+ missing,+ `${relPath} omits ${missing.length} shared setup file(s); it resolves ` ++ `[${setupFiles.join(', ')}]. Build it from okVitestBase.test.setupFiles ` ++ 'rather than listing entries by hand.',+ ).toEqual([]);+ });+});diff --git a/test-support/vitest.base.ts b/test-support/vitest.base.tsindex 8d07daaa3..07121d3ca 100644--- a/test-support/vitest.base.ts+++ b/test-support/vitest.base.ts@@ -11,7 +11,8 @@* instead of `src/` — tests would then run against stale build output. The* SSR resolver is the operative one for inlined workspace symlinks; the* client-side `resolve.conditions` is set too for safety.- * - `test.setupFiles` installs the `Bun` global facade before any test runs.+ * - `test.setupFiles` installs the `Bun` global facade and the hermetic-test+ * network guard (`no-net-connect.ts`) before any test runs.** `import.meta.dir` (bun-only, no trailing slash) is rewritten at transform time* to the Node-equivalent directory expression. Node's own `import.meta.dirname`@@ -68,7 +69,19 @@ export const importMetaDirPlugin: Plugin = {},};-export const bunGlobalShimPath = fileURLToPath(new URL('./bun-global-shim.ts', import.meta.url));+const bunGlobalShimPath = fileURLToPath(new URL('./bun-global-shim.ts', import.meta.url));++const noNetConnectPath = fileURLToPath(new URL('./no-net-connect.ts', import.meta.url));++// A project's `setupFiles` must be the base array: either spread into a new one+// (`[...okVitestBase.test.setupFiles, mine]`) or handed straight through. Not a+// hand-listed array, not one entry picked out of the base, not a filtered copy —+// each of those silently drops whichever guard the author left out, and the loss+// is invisible because the tests still pass. The two paths above stay unexported+// so the hand-rolled spelling is not reachable from outside this module, and+// `setup-files-contract.test.ts` imports every vitest project's config and fails+// any whose RESOLVED array omits an entry this base installs, so no spelling can+// route around it.export const okVitestBase = {plugins: [importMetaDirPlugin],@@ -91,7 +104,7 @@ export const okVitestBase = {// that wants to exercise the reporter injects its own `fetchImpl` and// `env`, so this never hides the behavior under test.env: { DO_NOT_TRACK: '1' },- setupFiles: [bunGlobalShimPath],+ setupFiles: [bunGlobalShimPath, noNetConnectPath],include: ['**/*.test.ts?(x)'],exclude: [...configDefaults.exclude, '**/*.spec.*', '**/*.e2e.*', '**/*.dom.test.ts?(x)'],// Vitest 4 flattened the pool sizing knobs to top-level `maxWorkers`/diff --git a/turbo.json b/turbo.jsonindex 7a3888b24..8058d8332 100644--- a/turbo.json+++ b/turbo.json@@ -98,7 +98,14 @@"@inkeep/open-knowledge#test": {"dependsOn": ["^build", "build"],"cache": true,- "inputs": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.json", "tests/contract/**/*.ts"]+ "inputs": [+ "src/**/*.ts",+ "src/**/*.tsx",+ "src/**/*.json",+ "tests/contract/**/*.ts",+ "vitest.config.ts",+ "../../test-support/*.ts"+ ]},"@inkeep/open-knowledge-desktop#test": {"dependsOn": ["^build"],