Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
import type { IncomingMessage, ServerResponse } from 'node:http';
import { createServer, type Server } from 'node:http';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, beforeEach, describe, expect, type Mock, test, vi } from 'vitest';
import { createApiExtension } from './api-extension.test-helper.ts';
import type { GuardRejectReason } from './link-preview/guarded-fetch.ts';
import type { GuardedFetch } from './link-preview/metadata.ts';
import { PinoLogger } from './logger.ts';
import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
const PREVIEW_URL = '/api/link-preview';
const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00]);
function makeFakeFetch(config: {
html?: string;
reason?: GuardRejectReason;
faviconBytes?: Uint8Array;
}): { impl: GuardedFetch; calls: string[] } {
const calls: string[] = [];
const impl: GuardedFetch = async (url, options) => {
calls.push(url);
const isFaviconFetch = options?.allowContentType?.('image/png') === true;
if (isFaviconFetch) {
if (!config.faviconBytes) return { ok: false, reason: 'non-html' };
return { ok: true, body: config.faviconBytes, contentType: 'image/png', finalUrl: url };
}
if (config.reason) return { ok: false, reason: config.reason };
return {
ok: true,
body: new TextEncoder().encode(config.html ?? ''),
contentType: 'text/html',
finalUrl: url,
};
};
return { impl, calls };
}
interface Harness {
baseURL: string;
close: () => Promise<void>;
}
async function startHarness(
contentDir: string,
linkPreviewFetch?: GuardedFetch,
getLinkPreviewsEnabled: (() => boolean) | null = () => true,
): Promise<Harness> {
const ext = createApiExtension({
hocuspocus: {} as Parameters<typeof createApiExtension>[0]['hocuspocus'],
sessionManager: {} as Parameters<typeof createApiExtension>[0]['sessionManager'],
contentDir,
serverInstanceId: 'test-server',
getFileIndex: () => new Map(),
linkPreviewFetch,
...(getLinkPreviewsEnabled === null ? {} : { getLinkPreviewsEnabled }),
});
const server: Server = createServer((req, res) => {
void (
ext as {
onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
}
).onRequest({ request: req, response: res });
});
const { baseUrl } = await listenOnLoopback(server);
return {
baseURL: baseUrl,
close: () =>
new Promise<void>((resolve, reject) => {
server.close((err) => (err ? reject(err) : resolve()));
}),
};
}
interface PostOptions {
origin?: string | null;
contentType?: string | null;
method?: string;
body?: string;
}
function postPreview(baseURL: string, options: PostOptions = {}): Promise<Response> {
const headers: Record<string, string> = {};
if (options.origin != null) headers.Origin = options.origin;
if (options.contentType != null) headers['Content-Type'] = options.contentType;
return fetch(`${baseURL}${PREVIEW_URL}`, {
method: options.method ?? 'POST',
headers,
body: options.method === 'GET' ? undefined : (options.body ?? '{}'),
});
}
function useHarness(): {
open: (
linkPreviewFetch?: GuardedFetch,
getLinkPreviewsEnabled?: (() => boolean) | null,
) => Promise<Harness>;
} {
let tmpDir = '';
let contentDir = '';
let opened: Harness | null = null;
beforeEach(() => {
tmpDir = mkdtempSync(join(tmpdir(), 'ok-link-preview-'));
contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
});
afterEach(async () => {
if (opened) {
await opened.close();
opened = null;
}
rmSync(tmpDir, { recursive: true, force: true });
});
return {
open: async (
linkPreviewFetch?: GuardedFetch,
getLinkPreviewsEnabled: (() => boolean) | null = () => true,
) => {
opened = await startHarness(contentDir, linkPreviewFetch, getLinkPreviewsEnabled);
return opened;
},
};
}
const jsonPost = (url: string) => ({
contentType: 'application/json',
body: JSON.stringify({ url }),
});
describe('POST /api/link-preview anti-proxy gate', () => {
const rig = useHarness();
test('rejects a cross-origin Origin without fetching', async () => {
const fake = makeFakeFetch({ html: '<title>never</title>' });
const harness = await rig.open(fake.impl);
const res = await postPreview(harness.baseURL, {
origin: 'https://evil.example',
...jsonPost('https://example.com'),
});
expect(res.status).toBe(403);
expect(fake.calls).toHaveLength(0);
});
test('rejects Origin: null (sandboxed iframe) without fetching', async () => {
const fake = makeFakeFetch({ html: '<title>never</title>' });
const harness = await rig.open(fake.impl);
const res = await postPreview(harness.baseURL, {
origin: 'null',
...jsonPost('https://example.com'),
});
expect(res.status).toBe(403);
expect(fake.calls).toHaveLength(0);
});
test('rejects an absent Origin without fetching', async () => {
const fake = makeFakeFetch({ html: '<title>never</title>' });
const harness = await rig.open(fake.impl);
const res = await postPreview(harness.baseURL, {
origin: null,
...jsonPost('https://example.com'),
});
expect(res.status).toBe(403);
expect(fake.calls).toHaveLength(0);
});
test('rejects a GET without fetching', async () => {
const fake = makeFakeFetch({ html: '<title>never</title>' });
const harness = await rig.open(fake.impl);
const res = await postPreview(harness.baseURL, { method: 'GET', origin: harness.baseURL });
expect(res.status).toBe(405);
expect(fake.calls).toHaveLength(0);
});
test('rejects a non-JSON content type with the shared 415 without fetching', async () => {
const fake = makeFakeFetch({ html: '<title>never</title>' });
const harness = await rig.open(fake.impl);
const res = await postPreview(harness.baseURL, {
origin: harness.baseURL,
contentType: 'text/plain',
body: JSON.stringify({ url: 'https://example.com' }),
});
expect(res.status).toBe(415);
expect(((await res.json()) as { type?: string }).type).toBe(
'urn:ok:error:unsupported-media-type',
);
expect(fake.calls).toHaveLength(0);
});
test('rejects a body missing the url field before fetching', async () => {
const fake = makeFakeFetch({ html: '<title>never</title>' });
const harness = await rig.open(fake.impl);
const res = await postPreview(harness.baseURL, {
origin: harness.baseURL,
contentType: 'application/json',
body: JSON.stringify({}),
});
expect(res.status).toBe(400);
expect(fake.calls).toHaveLength(0);
});
});
describe('POST /api/link-preview preview outcomes', () => {
const rig = useHarness();
test('returns card metadata for a well-formed same-origin POST', async () => {
const fake = makeFakeFetch({
html: '<head><title>Example Domain</title><meta name="description" content="A demo page"></head>',
});
const harness = await rig.open(fake.impl);
const res = await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost('https://example.com/page'),
});
expect(res.status).toBe(200);
const body = (await res.json()) as { ok: boolean; metadata?: Record<string, string> };
expect(body.ok).toBe(true);
expect(body.metadata?.domain).toBe('example.com');
expect(body.metadata?.title).toBe('Example Domain');
expect(body.metadata?.description).toBe('A demo page');
expect(fake.calls).toContain('https://example.com/page');
});
test('carries a validated favicon through as a data URI', async () => {
const fake = makeFakeFetch({
html: '<title>Iconic</title><link rel="icon" href="/favicon.ico">',
faviconBytes: PNG_BYTES,
});
const harness = await rig.open(fake.impl);
const res = await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost('https://example.com/'),
});
const body = (await res.json()) as { ok: boolean; metadata?: { faviconDataUri?: string } };
expect(body.ok).toBe(true);
const pngDataUri = 'data:image/png;base64,';
expect(body.metadata?.faviconDataUri?.slice(0, pngDataUri.length)).toBe(pngDataUri);
});
test('a guard rejection crosses the wire with the single coarse reason', async () => {
const fake = makeFakeFetch({ reason: 'private-ip' });
const harness = await rig.open(fake.impl);
const res = await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost('https://intranet.example'),
});
expect(res.status).toBe(200);
expect(await res.json()).toEqual({ ok: false, reason: 'blocked' });
});
test('distinct guard reasons are indistinguishable on the wire', async () => {
const dnsFake = makeFakeFetch({ reason: 'dns-failure' });
const harness = await rig.open(dnsFake.impl);
const res = await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost('https://does-not-resolve.example'),
});
expect(await res.json()).toEqual({ ok: false, reason: 'blocked' });
});
test('serves the cache-hit fast path without re-fetching', async () => {
const fake = makeFakeFetch({ html: '<title>Cached</title>' });
const harness = await rig.open(fake.impl);
const url = 'https://example.com/cached';
const first = await postPreview(harness.baseURL, { origin: harness.baseURL, ...jsonPost(url) });
const second = await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost(url),
});
expect(first.status).toBe(200);
expect(second.status).toBe(200);
const firstBody = await first.json();
const secondBody = await second.json();
expect(secondBody).toEqual(firstBody);
expect(fake.calls.filter((u) => u === url)).toHaveLength(1);
});
});
describe('POST /api/link-preview server-side linkPreviews.enabled enforcement', () => {
const rig = useHarness();
test('previews disabled: non-ok envelope, zero outbound fetches', async () => {
const fake = makeFakeFetch({ html: '<title>never</title>' });
const harness = await rig.open(fake.impl, () => false);
const res = await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost('https://example.com/'),
});
expect(res.status).toBe(200);
expect(await res.json()).toEqual({ ok: false, reason: 'disabled' });
expect(fake.calls).toHaveLength(0);
});
test('getter omitted entirely: fail-closed, zero outbound fetches', async () => {
const fake = makeFakeFetch({ html: '<title>never</title>' });
const harness = await rig.open(fake.impl, null);
const res = await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost('https://example.com/'),
});
expect(await res.json()).toEqual({ ok: false, reason: 'disabled' });
expect(fake.calls).toHaveLength(0);
});
test('a throwing config read is fail-closed, zero outbound fetches', async () => {
const fake = makeFakeFetch({ html: '<title>never</title>' });
const harness = await rig.open(fake.impl, () => {
throw new Error('config read failed');
});
const res = await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost('https://example.com/'),
});
expect(await res.json()).toEqual({ ok: false, reason: 'disabled' });
expect(fake.calls).toHaveLength(0);
});
test('the disabled short-circuit never poisons the cache: enabling serves a fresh preview', async () => {
const fake = makeFakeFetch({ html: '<title>Fresh</title>' });
let enabled = false;
const harness = await rig.open(fake.impl, () => enabled);
const url = 'https://example.com/toggled';
const off = await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost(url),
});
expect(await off.json()).toEqual({ ok: false, reason: 'disabled' });
expect(fake.calls).toHaveLength(0);
enabled = true;
const on = await postPreview(harness.baseURL, { origin: harness.baseURL, ...jsonPost(url) });
const body = (await on.json()) as { ok: boolean; metadata?: { title?: string } };
expect(body.ok).toBe(true);
expect(body.metadata?.title).toBe('Fresh');
});
});
describe('POST /api/link-preview real SSRF chokepoint', () => {
const rig = useHarness();
test('rejects a private-IP target with a structured failure', async () => {
const harness = await rig.open();
const res = await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost('http://127.0.0.1:9'),
});
expect(res.status).toBe(200);
expect(await res.json()).toEqual({ ok: false, reason: 'blocked' });
});
test('treats an empty url as a structured failure', async () => {
const harness = await rig.open();
const res = await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost(''),
});
expect(res.status).toBe(200);
const body = (await res.json()) as { ok: boolean; reason?: string };
expect(body.ok).toBe(false);
expect(typeof body.reason).toBe('string');
});
});
describe('POST /api/link-preview outcome instrumentation', () => {
const rig = useHarness();
let debugSpy: Mock<PinoLogger['debug']>;
beforeEach(() => {
debugSpy = vi.spyOn(PinoLogger.prototype, 'debug');
});
afterEach(() => {
debugSpy.mockRestore();
});
function loggedOutcomes(): unknown[] {
return debugSpy.mock.calls
.filter(([, message]) => message === '[link-preview] request outcome')
.map(([data]) => (data as { outcome?: unknown }).outcome);
}
test('the disabled short-circuit logs its outcome category', async () => {
const fake = makeFakeFetch({ html: '<title>never</title>' });
const harness = await rig.open(fake.impl, () => false);
await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost('https://example.com/'),
});
expect(loggedOutcomes()).toEqual(['disabled']);
});
test('a fresh fetch logs fetched-ok and the warm re-hover logs cache-hit', async () => {
const fake = makeFakeFetch({ html: '<title>Logged</title>' });
const harness = await rig.open(fake.impl);
const url = 'https://example.com/logged';
await postPreview(harness.baseURL, { origin: harness.baseURL, ...jsonPost(url) });
await postPreview(harness.baseURL, { origin: harness.baseURL, ...jsonPost(url) });
expect(loggedOutcomes()).toEqual(['fetched-ok', 'cache-hit']);
});
test('a guard rejection logs fallback, and the record is the category alone', async () => {
const fake = makeFakeFetch({ reason: 'private-ip' });
const harness = await rig.open(fake.impl);
await postPreview(harness.baseURL, {
origin: harness.baseURL,
...jsonPost('https://intranet.example/secret-path'),
});
expect(loggedOutcomes()).toEqual(['fallback']);
const outcomeCalls = debugSpy.mock.calls.filter(
([, message]) => message === '[link-preview] request outcome',
);
for (const [data] of outcomeCalls) {
expect(Object.keys(data as Record<string, unknown>)).toEqual(['outcome']);
}
});
});