Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import type { ServerRuntimeConfig } from '@inkeep/open-knowledge-core';
import { describe, expect, test } from 'vitest';
import {
admitRequestOrigin,
buildIngressPolicy,
getIngressContext,
hasForwardingHeaders,
hostHeaderMatchesExternalHost,
isHostAdmitted,
isOriginAdmitted,
isPeerAdmitted,
normalizeHostHeader,
OPAQUE_ORIGIN_REFUSAL_DETAIL,
stampIngressContext,
tripsForwardedHeaderTripwire,
} from './ingress-policy.ts';
function runtime(overrides: Partial<ServerRuntimeConfig> = {}): ServerRuntimeConfig {
return {
port: undefined,
bind: ['127.0.0.1'],
externalUrl: undefined,
allowExternal: false,
openBrowser: true,
idleShutdown: '30m',
loopbackOnly: true,
...overrides,
};
}
const TUNNEL_EXPOSURE_RUNTIME: Partial<ServerRuntimeConfig> = {
externalUrl: 'https://myproject.ngrok.app',
allowExternal: true,
idleShutdown: 'off',
openBrowser: false,
};
describe('buildIngressPolicy', () => {
test('empty input yields the loopback-only default policy', () => {
const policy = buildIngressPolicy({});
expect(policy.allowExternal).toBe(false);
expect(policy.bindLiterals).toEqual([]);
expect(policy.externalOrigin).toBeUndefined();
expect(policy.tolerateForwardedHeaders).toBe(false);
});
test('non-loopback bind literals are collected; loopback and wildcards are not', () => {
const policy = buildIngressPolicy({
serverRuntime: runtime({
bind: ['127.0.0.1', '100.64.0.7', '0.0.0.0', '::', 'localhost', '[::1]', '2001:DB8::1'],
loopbackOnly: false,
}),
});
expect(policy.bindLiterals).toEqual(['100.64.0.7', '2001:db8::1']);
});
test('externalOrigin comes from a server-sourced externalUrl', () => {
const explicit = buildIngressPolicy({
serverRuntime: runtime({
externalUrl: 'http://laptop.tail:55222',
}),
});
expect(explicit.externalOrigin).toEqual({ host: 'laptop.tail:55222', protocol: 'http:' });
const none = buildIngressPolicy({ serverRuntime: runtime({}) });
expect(none.externalOrigin).toBeUndefined();
});
test('forwarded headers are tolerated only under consent + declared externalUrl', () => {
expect(
buildIngressPolicy({ serverRuntime: runtime(TUNNEL_EXPOSURE_RUNTIME) })
.tolerateForwardedHeaders,
).toBe(true);
expect(
buildIngressPolicy({
serverRuntime: runtime({
allowExternal: true,
externalUrl: 'https://kb.example.com',
}),
}).tolerateForwardedHeaders,
).toBe(true);
expect(
buildIngressPolicy({
serverRuntime: runtime({ allowExternal: true, loopbackOnly: false }),
}).tolerateForwardedHeaders,
).toBe(false);
expect(
buildIngressPolicy({
serverRuntime: runtime({
externalUrl: 'https://kb.example.com',
}),
}).tolerateForwardedHeaders,
).toBe(false);
});
});
describe('isPeerAdmitted — consent relaxes the peer gate ONLY', () => {
test('loopback always passes; external requires allowExternal', () => {
const local = buildIngressPolicy({});
expect(isPeerAdmitted('127.0.0.1', local)).toBe(true);
expect(isPeerAdmitted('::1', local)).toBe(true);
expect(isPeerAdmitted('100.64.0.9', local)).toBe(false);
const consented = buildIngressPolicy({
serverRuntime: runtime({ allowExternal: true, loopbackOnly: false }),
});
expect(isPeerAdmitted('100.64.0.9', consented)).toBe(true);
expect(isPeerAdmitted('203.0.113.7', consented)).toBe(true);
});
test('a vanished socket stays refused even with consent', () => {
const consented = buildIngressPolicy({
serverRuntime: runtime({ allowExternal: true, loopbackOnly: false }),
});
expect(isPeerAdmitted(undefined, consented)).toBe(false);
});
});
describe('isHostAdmitted — names validate in every mode, never widened by consent', () => {
const case2 = buildIngressPolicy({
serverRuntime: runtime({
bind: ['127.0.0.1', '100.64.0.7'],
loopbackOnly: false,
allowExternal: true,
externalUrl: 'http://laptop.tail:55222',
}),
});
test('loopback names and bind literals (any port) are admitted', () => {
expect(isHostAdmitted('localhost:5173', case2)).toBe(true);
expect(isHostAdmitted('100.64.0.7:55222', case2)).toBe(true);
expect(isHostAdmitted('100.64.0.7', case2)).toBe(true);
});
test('the declared externalUrl host is admitted exactly (host:port)', () => {
expect(isHostAdmitted('laptop.tail:55222', case2)).toBe(true);
expect(isHostAdmitted('laptop.tail:9999', case2)).toBe(false);
});
test('unconfigured names stay refused even under consent (rebinding defense)', () => {
expect(isHostAdmitted('evil.example', case2)).toBe(false);
expect(isHostAdmitted('evil.example:55222', case2)).toBe(false);
expect(isHostAdmitted(undefined, case2)).toBe(false);
});
test('an IPv6 bind literal matches its bracketed Host form', () => {
const v6 = buildIngressPolicy({
serverRuntime: runtime({ bind: ['2001:db8::1'], loopbackOnly: false, allowExternal: true }),
});
expect(isHostAdmitted('[2001:db8::1]:8080', v6)).toBe(true);
expect(isHostAdmitted('[2001:db8::2]:8080', v6)).toBe(false);
});
test('a malformed bracketed-IPv6 Host is refused (fail-closed parse)', () => {
const v6 = buildIngressPolicy({
serverRuntime: runtime({ bind: ['2001:db8::1'], loopbackOnly: false, allowExternal: true }),
});
expect(isHostAdmitted('[2001:db8::1', v6)).toBe(false);
expect(isHostAdmitted('[2001:db8::1:8080', v6)).toBe(false);
});
});
describe('isOriginAdmitted — if present, must match; scheme-matched for externalUrl', () => {
const case3 = buildIngressPolicy({
serverRuntime: runtime({
allowExternal: true,
externalUrl: 'https://notes.example.com',
}),
});
test('the declared public origin is admitted; wrong scheme refused', () => {
expect(isOriginAdmitted('https://notes.example.com', case3)).toBe(true);
expect(isOriginAdmitted('http://notes.example.com', case3)).toBe(false);
expect(isOriginAdmitted('https://evil.example.com', case3)).toBe(false);
});
test('an http externalUrl admits its http origin (tailnet/LAN posture)', () => {
const httpPublic = buildIngressPolicy({
serverRuntime: runtime({
allowExternal: true,
externalUrl: 'http://laptop.tail:55222',
}),
});
expect(isOriginAdmitted('http://laptop.tail:55222', httpPublic)).toBe(true);
expect(isOriginAdmitted('https://laptop.tail:55222', httpPublic)).toBe(false);
});
test('bind-literal origins are admitted over http or https', () => {
const bound = buildIngressPolicy({
serverRuntime: runtime({
bind: ['100.64.0.7'],
loopbackOnly: false,
allowExternal: true,
}),
});
expect(isOriginAdmitted('http://100.64.0.7:55222', bound)).toBe(true);
expect(isOriginAdmitted('https://100.64.0.7', bound)).toBe(true);
expect(isOriginAdmitted('ftp://100.64.0.7', bound)).toBe(false);
});
test('loopback and the desktop file:// shape pass; the sandboxed-frame null origin never does', () => {
const local = buildIngressPolicy({});
expect(isOriginAdmitted('http://localhost:5173', local)).toBe(true);
expect(isOriginAdmitted('null', local)).toBe(false);
expect(isOriginAdmitted('null', case3)).toBe(false);
expect(isOriginAdmitted('file://', local)).toBe(true);
expect(isOriginAdmitted('https://evil.example.com', local)).toBe(false);
});
test('a malformed / unparseable Origin fails closed under consent', () => {
expect(isOriginAdmitted('http://[not-closed', case3)).toBe(false);
expect(isOriginAdmitted('://missing-scheme', case3)).toBe(false);
expect(isOriginAdmitted('not a url', case3)).toBe(false);
expect(isOriginAdmitted('https://', case3)).toBe(false);
});
});
describe('tunnel admission via the ratified keys', () => {
const tunnel = buildIngressPolicy({ serverRuntime: runtime(TUNNEL_EXPOSURE_RUNTIME) });
test('the tunnel public Host is admitted, with or without default-port suffix', () => {
expect(isHostAdmitted('myproject.ngrok.app', tunnel)).toBe(true);
expect(isHostAdmitted('myproject.ngrok.app:443', tunnel)).toBe(true);
expect(isHostAdmitted('127.0.0.1:24550', tunnel)).toBe(true);
expect(isHostAdmitted('evil.example.com', tunnel)).toBe(false);
expect(isHostAdmitted(undefined, tunnel)).toBe(false);
});
test('the https tunnel origin is admitted; http and foreign origins are not', () => {
expect(isOriginAdmitted('https://myproject.ngrok.app', tunnel)).toBe(true);
expect(isOriginAdmitted('http://myproject.ngrok.app', tunnel)).toBe(false);
expect(isOriginAdmitted('https://evil.example.com', tunnel)).toBe(false);
});
test('forwarding headers (tunnels always inject them) do not trip the wire', () => {
expect(
tripsForwardedHeaderTripwire({ headers: { 'x-forwarded-for': '203.0.113.7' } }, tunnel),
).toBe(false);
});
});
describe('normalizeHostHeader / hostHeaderMatchesExternalHost', () => {
test('matches the public host, with or without default-port suffix, case-insensitively', () => {
expect(normalizeHostHeader('MyProject.NGROK.app:443')).toBe('myproject.ngrok.app');
expect(normalizeHostHeader('host.example:8080')).toBe('host.example:8080');
expect(hostHeaderMatchesExternalHost('myproject.ngrok.app', 'myproject.ngrok.app')).toBe(true);
expect(hostHeaderMatchesExternalHost('myproject.ngrok.app:443', 'myproject.ngrok.app')).toBe(
true,
);
expect(hostHeaderMatchesExternalHost('MyProject.NGROK.app', 'myproject.ngrok.app')).toBe(true);
});
test('refuses other hosts and missing Host', () => {
expect(hostHeaderMatchesExternalHost('evil.example.com', 'myproject.ngrok.app')).toBe(false);
expect(hostHeaderMatchesExternalHost(undefined, 'myproject.ngrok.app')).toBe(false);
});
});
describe('hasForwardingHeaders', () => {
test('detects standard forwarding headers; plain local requests carry none', () => {
expect(hasForwardingHeaders({ headers: { 'x-forwarded-for': '203.0.113.7' } })).toBe(true);
expect(hasForwardingHeaders({ headers: { forwarded: 'for=203.0.113.7' } })).toBe(true);
expect(hasForwardingHeaders({ headers: { host: 'localhost:24550' } })).toBe(false);
});
});
describe('tripsForwardedHeaderTripwire', () => {
test('fires on forwarding headers unless the policy tolerates them', () => {
const local = buildIngressPolicy({});
const req = { headers: { 'x-forwarded-for': '203.0.113.7' } };
expect(tripsForwardedHeaderTripwire(req, local)).toBe(true);
const consented = buildIngressPolicy({
serverRuntime: runtime({
allowExternal: true,
externalUrl: 'https://notes.example.com',
}),
});
expect(tripsForwardedHeaderTripwire(req, consented)).toBe(false);
expect(tripsForwardedHeaderTripwire({ headers: {} }, local)).toBe(false);
});
test.each([
'x-forwarded-for',
'x-forwarded-proto',
'x-forwarded-host',
'forwarded',
'x-real-ip',
'x-client-ip',
'x-cluster-client-ip',
'cf-connecting-ip',
'fastly-client-ip',
'true-client-ip',
])('fires on the %s forwarding header (non-consented)', (header) => {
const local = buildIngressPolicy({});
expect(tripsForwardedHeaderTripwire({ headers: { [header]: 'v' } }, local)).toBe(true);
});
});
describe('ingress request context', () => {
test('stamps peer class and the empty actor slot, retrievable by request', () => {
const req = {
socket: { remoteAddress: '100.64.0.9' },
headers: {},
} as unknown as import('node:http').IncomingMessage;
const context = stampIngressContext(req, { requestId: 'r-1' });
expect(context).toStrictEqual({
requestId: 'r-1',
peerClass: 'external',
clientSurface: undefined,
actor: undefined,
});
expect(getIngressContext(req)).toBe(context);
});
test('carries the client surface the pipeline read for the request', () => {
const req = {
socket: { remoteAddress: '127.0.0.1' },
headers: {},
} as unknown as import('node:http').IncomingMessage;
stampIngressContext(req, { requestId: 'r-2', clientSurface: 'embedded:codex' });
expect(getIngressContext(req)?.clientSurface).toBe('embedded:codex');
});
});
describe('admitRequestOrigin', () => {
const local = buildIngressPolicy({});
const opaqueRefusal = { admitted: false, detail: OPAQUE_ORIGIN_REFUSAL_DETAIL };
test('no Origin and site origins are admitted with the CORS grant', () => {
expect(admitRequestOrigin(undefined, 'POST', local)).toEqual({
admitted: true,
corsGrant: true,
});
expect(admitRequestOrigin('http://localhost:5173', 'GET', local)).toEqual({
admitted: true,
corsGrant: true,
});
expect(admitRequestOrigin('http://127.0.0.1:4000', 'DELETE', local)).toEqual({
admitted: true,
corsGrant: true,
});
});
test('a null origin is refused for every method with the opaque-origin detail', () => {
for (const method of ['GET', 'HEAD', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']) {
expect(admitRequestOrigin('null', method, local), method).toEqual(opaqueRefusal);
}
});
test('a file: origin may read without a grant and may not write', () => {
for (const method of ['GET', 'HEAD', 'OPTIONS']) {
expect(admitRequestOrigin('file://', method, local), method).toEqual({
admitted: true,
corsGrant: false,
});
}
for (const method of ['POST', 'PUT', 'PATCH', 'DELETE']) {
expect(admitRequestOrigin('file://', method, local), method).toEqual(opaqueRefusal);
}
});
test('a foreign origin is refused without the opaque-origin detail', () => {
expect(admitRequestOrigin('https://evil.example', 'GET', local)).toEqual({
admitted: false,
detail: undefined,
});
});
});