Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(ok): Host-gate /api reads and content-asset serving (PRD-7901) (#3394)

omar-inkeep665c87e35e81
diff --git a/.changeset/read-posture-hardening.md b/.changeset/read-posture-hardening.md
new file mode 100644
index 000000000..5b8ec0c08
--- /dev/null
+++ b/.changeset/read-posture-hardening.md
@@ -0,0 +1,10 @@
+---
+'@inkeep/open-knowledge': minor
+---
+
+Read-posture hardening: every `/api` read and content-asset serve now validates the Host header, closing a DNS-rebinding read-exfil hole on exposed servers.
+
+- Previously, mutating routes were Host-gated but reads (`GET /api/*`) were Origin-gated only in normal mode. A DNS-rebound page's same-origin GET carries no Origin, so document content could be read cross-origin under exposure. Reads now share the same Host admission writes already use: a request must present a Host in the admitted set (loopback names, `server.bind` literals, `server.publicUrl` host) or it is refused with `403 host-not-allowed`. This is the no-auth compensating control — no credentials are involved.
+- Content-asset serving (`/api/asset` sibling static path) is gated the same way, so uploaded images/PDFs/attachments can't be read under a rebound Host either. The extension-less SPA shell stays reachable under any Host (it's public bundle code); only actual content-serve attempts are gated.
+- If you reach a server by a hostname it hasn't been told about, reads now return `403 host-not-allowed`. Declare the name via `server.publicUrl` (or bind to it via `server.bind`) so it's admitted. Loopback access (`localhost`/`127.0.0.1`/`[::1]`) is unaffected, as is any first-party client on a loopback-shaped Host.
+- `createAssetServeMiddleware` (from `@inkeep/open-knowledge-server`) now takes a required `ingressPolicy`. Surfaces with a resolved runtime pass their boot-built policy; loopback-only surfaces (the Vite dev plugin, the `ok ui` sidecar) pass `buildIngressPolicy({})`. This is a required-parameter addition on a package export, but `@inkeep/open-knowledge-server` is `private: true` (never published to npm — internal to the `@inkeep/open-knowledge` CLI), so it is not a public-API break; the bump is `minor` on the only published package, whose CLI command surface is unchanged.
diff --git a/knip.config.ts b/knip.config.ts
index 78162ec09..f9179f2d4 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -123,7 +123,9 @@ export default {
'packages/server': {
entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],
project: 'src/**',
- ignoreDependencies: ['@types/shell-quote'],
+ ignoreDependencies: [
+ '@types/shell-quote',
+ ],
},
'packages/cli': {
entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],
diff --git a/packages/app/src/server/hocuspocus-plugin.ts b/packages/app/src/server/hocuspocus-plugin.ts
index 63e196b8a..deb090c40 100644
--- a/packages/app/src/server/hocuspocus-plugin.ts
+++ b/packages/app/src/server/hocuspocus-plugin.ts
@@ -23,6 +23,7 @@ import {
} from '@inkeep/open-knowledge-core';
import {
AcpThreadManager,
+ buildIngressPolicy,
buildOkMcpStdioCommand,
createAssetServeMiddleware,
createCollaborationHost,
@@ -312,6 +313,15 @@ export function hocuspocusPlugin(): Plugin {
inlineExtensions: INLINE_RENDERABLE_EXTENSIONS,
assetExtensions: ASSET_EXTENSIONS,
blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,
+ // Dev serves on the Vite loopback port with no resolved server
+ // runtime — the loopback-only default admits the localhost Hosts
+ // the browser actually sends. Known dev-mode limitation: under
+ // `vite --host` (LAN testing from a phone/second machine) content
+ // assets 403 while the shell still loads, so images render broken —
+ // there is no dev-side publicUrl to admit the LAN Host. For LAN/tailnet
+ // testing use `ok start --bind <ip>` + `OK_PUBLIC_URL`, which builds a
+ // real policy that admits the declared Host.
+ ingressPolicy: buildIngressPolicy({}),
});
server.middlewares.use((req, res, next) => {
const url = req.url ?? '';
diff --git a/packages/app/tests/integration/single-file-mode.test.ts b/packages/app/tests/integration/single-file-mode.test.ts
index e86fd85a5..35f23f36b 100644
--- a/packages/app/tests/integration/single-file-mode.test.ts
+++ b/packages/app/tests/integration/single-file-mode.test.ts
@@ -335,10 +335,11 @@ describe('single-file mode — /api host gate (DNS-rebinding defense)', () => {
}
});
- test('non-ephemeral (project mode): a rebound Host on a read is NOT ephemeral-gated', async () => {
- // The ephemeral gate must not touch project/desktop read serving — the user
- // chose that root. A rebound-Host read there keeps its prior origin-only
- // posture (here: served, since a server-to-server fetch sends no Origin).
+ test('non-ephemeral (project mode): a rebound Host on a read is refused too', async () => {
+ // Flipped pin (read-posture hardening): the pipeline Host-gates every
+ // /api read in normal mode as well, so project/desktop reads refuse a
+ // rebound Host with the same wire shape the ephemeral gate uses. A
+ // loopback Host keeps serving (covered by the test above).
const contentDir = ephemeralContentDir({ 'notes.md': '# Notes\n' });
const server = await createTestServer({ contentDir, keepContentDir: true });
try {
@@ -346,7 +347,8 @@ describe('single-file mode — /api host gate (DNS-rebinding defense)', () => {
`http://127.0.0.1:${server.port}/api/document?docName=notes`,
REBIND_HOST,
);
- expect(res.status).not.toBe(403);
+ expect(res.status).toBe(403);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:host-not-allowed');
} finally {
await server.cleanup();
}
diff --git a/packages/cli/src/commands/ui.test.ts b/packages/cli/src/commands/ui.test.ts
index e509f3410..e92cd817e 100644
--- a/packages/cli/src/commands/ui.test.ts
+++ b/packages/cli/src/commands/ui.test.ts
@@ -974,20 +974,52 @@ describe('startUiServer', () => {
}
});
- test('non-/api/* paths are NOT subject to the gate (Host check would harm SPA)', async () => {
- // The gate is scoped to /api/* — static asset / SPA paths must continue to
- // serve regardless of Host (a browser navigating via different loopback
- // hostnames legitimately sends different Host values; the asset path is
- // not state-mutating). Sanity-check that an asset-extension URL with an
- // attacker Host reaches the asset middleware, which 404s for a missing
- // file rather than 403ing on the Host.
+ test('content-asset paths are Host-gated; SPA paths stay ungated', async () => {
+ // Flipped pin (read-posture hardening): an asset-extension URL is a
+ // content-serve attempt, so the in-middleware gate refuses a rebound
+ // Host BEFORE the disk lookup (403 host-not-allowed, not the miss 404).
+ // Extension-less SPA paths still serve regardless of Host — the shell is
+ // public bundle code, and a browser navigating via different loopback
+ // hostnames legitimately varies its Host.
handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
- const res = await rawRequest({
+ const gated = await rawRequest({
port: handle.port,
path: '/missing.png',
host: 'attacker.com:1234',
});
- expect(res.status).not.toBe(403);
+ expect(gated.status).toBe(403);
+ expect((JSON.parse(gated.body) as { type: string }).type).toBe('urn:ok:error:host-not-allowed');
+
+ const spa = await rawRequest({
+ port: handle.port,
+ path: '/some/deep-link',
+ host: 'attacker.com:1234',
+ });
+ expect(spa.status).not.toBe(403);
+ });
+
+ test('shell root (GET / -> /index.html) is gated under a rebound Host; serves over loopback', async () => {
+ // `ok ui` rewrites `GET /` (and `/index.html`) to an html-extension
+ // content-serve attempt BEFORE this middleware, and `.html` is an
+ // ASSET_EXTENSIONS member — so the shell root goes through the
+ // content-serve gate here (asset-serve-middleware policy item 0). `ok ui`
+ // is loopback-only (its `/api` gate is loopback-only too), so a rebound
+ // Host at the root is refused; a loopback Host serves the SPA shell.
+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });
+ for (const path of ['/', '/index.html']) {
+ const gated = await rawRequest({ port: handle.port, path, host: 'attacker.com:1234' });
+ expect(gated.status, path).toBe(403);
+ expect((JSON.parse(gated.body) as { type: string }).type).toBe(
+ 'urn:ok:error:host-not-allowed',
+ );
+ }
+ const loopback = await rawRequest({
+ port: handle.port,
+ path: '/',
+ host: `127.0.0.1:${handle.port}`,
+ });
+ expect(loopback.status).toBe(200);
+ expect(loopback.body).toContain('<!doctype html>');
});
test('asset serve: non-inline admitted asset gets Content-Disposition: attachment', async () => {
diff --git a/packages/cli/src/commands/ui.ts b/packages/cli/src/commands/ui.ts
index 6dfdb164e..b91f3300a 100644
--- a/packages/cli/src/commands/ui.ts
+++ b/packages/cli/src/commands/ui.ts
@@ -204,6 +204,7 @@ export async function startUiServer(opts: StartUiServerOptions): Promise<UiServe
const { resolve } = await import('node:path');
const {
acquireUiLock,
+ buildIngressPolicy,
createAssetServeMiddleware,
createContentFilter,
readServerLock,
@@ -280,6 +281,15 @@ export async function startUiServer(opts: StartUiServerOptions): Promise<UiServe
inlineExtensions: INLINE_RENDERABLE_EXTENSIONS,
assetExtensions: ASSET_EXTENSIONS,
blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,
+ // Loopback-only, matching this surface's `/api` gate. `ok ui`'s API
+ // gate is `rejectIfNotLoopbackApi` (loopback-shaped Host only, never
+ // policy-aware), so the content-serve gate must admit no wider a set —
+ // otherwise a config-declared `publicUrl` would serve content assets
+ // to a Host that every `/api` call on the same surface 403s, a
+ // half-broken app. `ok ui` is a loopback sidecar; the data server
+ // (`ok start`) is the exposable surface and builds the real policy.
+ // Mirrors the Vite dev plugin's loopback-only default.
+ ingressPolicy: buildIngressPolicy({}),
})
: null;
diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.ts
index d7a845280..dfd95ef49 100644
--- a/packages/core/src/bridge/bind-frontmatter-doc.ts
+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts
@@ -1,3 +1,4 @@
+
import type * as Y from 'yjs';
import type { Err, Ok, Result } from '../config/result.ts';
import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';
diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.ts
index 005627195..8bfdb40cd 100644
--- a/packages/core/src/bridge/bridge-invariant.ts
+++ b/packages/core/src/bridge/bridge-invariant.ts
@@ -1,3 +1,4 @@
+
import { fnv1aDigest } from './hash-util.ts';
export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';
diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.ts
index f4cc8a286..2a597ec3d 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,3 +1,4 @@
+
import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';
export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';
diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.ts
index 8fb428b90..01ef76a9f 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,3 +1,4 @@
+
import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';
import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';
diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.ts
index 9d9c244b0..463e89595 100644
--- a/packages/core/src/bridge/growth-detect.ts
+++ b/packages/core/src/bridge/growth-detect.ts
@@ -1,3 +1,4 @@
+
const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;
export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;
diff --git a/packages/core/src/bridge/intraline-predicate.ts b/packages/core/src/bridge/intraline-predicate.ts
index c43fdd7e7..0939885bb 100644
--- a/packages/core/src/bridge/intraline-predicate.ts
+++ b/packages/core/src/bridge/intraline-predicate.ts
@@ -1,3 +1,4 @@
+
export function rawLineCounts(doc: string): Map<string, number> {
const counts = new Map<string, number>();
for (const line of doc.split('\n')) {
diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.ts
index 251560a35..c0dc65705 100644
--- a/packages/core/src/bridge/merge-three-way.ts
+++ b/packages/core/src/bridge/merge-three-way.ts
@@ -65,6 +65,7 @@ export function tryLineLevelCombine(
return { clean: true, merged };
}
+
export type BridgeMergeContentLossSide = 'user' | 'agent';
export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';
diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.ts
index 01ac80099..dcc5b0690 100644
--- a/packages/core/src/bridge/normalize.ts
+++ b/packages/core/src/bridge/normalize.ts
@@ -1,3 +1,4 @@
+
import { stripFrontmatter } from '../extensions/frontmatter.ts';
import { bodyEdgeEmpties } from './doc-boundary-space.ts';
diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.ts
index 754dc5cc2..0be5203e4 100644
--- a/packages/core/src/bridge/pm-structural-equivalence.ts
+++ b/packages/core/src/bridge/pm-structural-equivalence.ts
@@ -32,6 +32,7 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };
const BR_LITERAL_RE = /^<br\s*\/?>$/i;
+
interface DegradeEntry {
readonly label: string;
readonly severity: ToleranceClassSeverity;
@@ -127,6 +128,7 @@ export interface ComparePmStructuralOptions {
ignoreAttrs?: (attrKey: string) => boolean;
}
+
/** Rebuild a node with `fn` applied to each child; identity when childless.
* Shared by the degrade canonicalizers so none re-implements the walk. */
function mapChildren(
@@ -248,6 +250,7 @@ function applyDegrades(tree: PmStructuralNode): {
return { normalized: current, fired };
}
+
export function comparePmStructural(
expected: PmStructuralNode,
actual: PmStructuralNode,
diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.ts
index af20de1e2..dca644141 100644
--- a/packages/core/src/bridge/subsequence.ts
+++ b/packages/core/src/bridge/subsequence.ts
@@ -1,3 +1,4 @@
+
/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):
* insertions in `haystack` are free; any dropped or substituted `needle` byte
* fails. */
diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.ts
index 83d47404a..a363dfd54 100644
--- a/packages/core/src/markdown/callout-transformer.ts
+++ b/packages/core/src/markdown/callout-transformer.ts
@@ -1,3 +1,4 @@
+
import type { Blockquote, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/code-fence.ts b/packages/core/src/markdown/code-fence.ts
index 9807a7e82..4499dbc92 100644
--- a/packages/core/src/markdown/code-fence.ts
+++ b/packages/core/src/markdown/code-fence.ts
@@ -1,3 +1,4 @@
+
export function selectFenceChar(info: string): '`' | '~' {
return info.includes('`') ? '~' : '`';
}
diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.ts
index 7415c474a..34704165b 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.ts
index ece5c02a1..b6299a948 100644
--- a/packages/core/src/markdown/dedent-block-jsx-close.ts
+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts
@@ -1,3 +1,4 @@
+
import { findFencedRegions, isInsideFence } from './fence-regions.ts';
const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;
diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.ts
index 54774764a..acd398aa6 100644
--- a/packages/core/src/markdown/details-accordion-promoter.ts
+++ b/packages/core/src/markdown/details-accordion-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/div-align-promoter.ts b/packages/core/src/markdown/div-align-promoter.ts
index 43ecdc709..ba9b56384 100644
--- a/packages/core/src/markdown/div-align-promoter.ts
+++ b/packages/core/src/markdown/div-align-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';
import type { MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.ts
index 6d3f3643e..4513da9bb 100644
--- a/packages/core/src/markdown/fence-regions.ts
+++ b/packages/core/src/markdown/fence-regions.ts
@@ -1,3 +1,4 @@
+
const FENCE_RE = /^(`{3,}|~{3,})/gm;
export function findFencedRegions(src: string): Array<[number, number]> {
diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.ts
index 00f5771ee..6931623c7 100644
--- a/packages/core/src/markdown/fixtures/index.ts
+++ b/packages/core/src/markdown/fixtures/index.ts
@@ -1,3 +1,4 @@
+
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -8,6 +9,7 @@ function fixturePath(...segments: string[]): string {
return resolve(FIXTURES_DIR, ...segments);
}
+
interface GfmExample {
section: string;
markdown: string;
@@ -17,6 +19,7 @@ export function loadGfmExamples(): GfmExample[] {
return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];
}
+
interface MdxCrashEntry {
id: string;
input: string;
@@ -68,6 +71,7 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {
) as LargeEmbedFixture[];
}
+
export function loadPrd6955Before(): string {
return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');
}
@@ -76,6 +80,7 @@ export function loadPrd6955CorruptedTriplicated(): string {
return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');
}
+
export interface NgPinnedCase {
id: string;
name: string;
@@ -92,6 +97,7 @@ export function loadNgPinnedCases(): NgPinnedCase[] {
) as NgPinnedCase[];
}
+
export function loadLargeRealistic(): string {
return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');
}
diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.ts
index 8b1eb8519..daa3ef82b 100644
--- a/packages/core/src/markdown/fixtures/perf/generate.ts
+++ b/packages/core/src/markdown/fixtures/perf/generate.ts
@@ -1,3 +1,4 @@
+
import { writeFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -10,6 +11,7 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;
const SEED = 0xf1de1117;
+
function mulberry32(seed: number): () => number {
let a = seed >>> 0;
return () => {
@@ -36,6 +38,7 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {
return items[items.length - 1][0];
}
+
const WORDS = [
'lorem',
'ipsum',
@@ -153,6 +156,7 @@ function mdxBlock(rand: () => number): string {
return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;
}
+
type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';
const MIX: readonly [BlockKind, number][] = [
@@ -191,6 +195,7 @@ function generateDocument(blockCount: number, seed: number): string {
return `${blocks.join('\n\n')}\n`;
}
+
function main(): void {
for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {
const doc = generateDocument(count, SEED);
diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.ts
index 420dc0fe5..32c055c5b 100644
--- a/packages/core/src/markdown/guard-flanking-matrix.ts
+++ b/packages/core/src/markdown/guard-flanking-matrix.ts
@@ -7,6 +7,7 @@ import {
import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';
import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';
+
export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;
export type FlankClass = 'whitespace' | 'punctuation' | 'other';
diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.ts
index 2653473da..283913255 100644
--- a/packages/core/src/markdown/handler-shadow-audit.ts
+++ b/packages/core/src/markdown/handler-shadow-audit.ts
@@ -1,3 +1,4 @@
+
export interface HandlerShadowWitness {
input: string;
expect: 'byte' | 'byte-and-reparse-type';
diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.ts
index da0a81d23..5d1000cc4 100644
--- a/packages/core/src/markdown/highlight-promoter.ts
+++ b/packages/core/src/markdown/highlight-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';
import type { MdxJsxTextElement } from 'mdast-util-mdx';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.ts
index 787315157..9681c0056 100644
--- a/packages/core/src/markdown/html-to-mdast.ts
+++ b/packages/core/src/markdown/html-to-mdast.ts
@@ -1,3 +1,4 @@
+
import type { Element as HastElement, Root as HastRoot } from 'hast';
import type { List, Nodes as MdastNodes, Root as MdastRoot } from 'mdast';
import rehypeParse from 'rehype-parse';
@@ -128,7 +129,8 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRo
throw new HtmlPayloadTooLargeError(html.length, maxBytes);
}
- const processor = unified().use(rehypeParse, { fragment: true });
+ const processor = unified()
+ .use(rehypeParse, { fragment: true });
for (const plugin of cleanupPlugins) {
processor.use(plugin);
diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.ts
index 706fa9afb..994eb6917 100644
--- a/packages/core/src/markdown/image-promoter.ts
+++ b/packages/core/src/markdown/image-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Image, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.ts
index 9075aa7f1..69221627d 100644
--- a/packages/core/src/markdown/index.ts
+++ b/packages/core/src/markdown/index.ts
@@ -1,3 +1,4 @@
+
import {
type FromProseMirrorOptions,
fromPmMark,
@@ -206,6 +207,7 @@ export class MarkdownManager {
}
}
+
const registry = createRegistry();
function destructureAttrs(
@@ -254,6 +256,7 @@ function destructureAttrs(
return result;
}
+
function hasDirtyDescendant(node: PmNode): boolean {
let found = false;
node.descendants((child) => {
@@ -276,6 +279,7 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChec
return freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;
}
+
function isEmptyMdastParagraph(node: MdastNodes): boolean {
if (node.type !== 'paragraph') return false;
const children = node.children ?? [];
@@ -344,6 +348,7 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {
return out;
}
+
import {
AUDIO_EXTENSIONS,
FILE_ATTACHMENT_EXTENSIONS,
@@ -596,6 +601,7 @@ function buildMdastToPmHandlers(
}));
}
+
if (m.emphasis) {
handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({
sourceDelimiter: node.data?.sourceDelimiter ?? '*',
@@ -676,6 +682,7 @@ function buildMdastToPmHandlers(
}));
}
+
if (m.link) {
const sourceLiteralMark = m.sourceLiteral;
handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {
@@ -973,6 +980,7 @@ function buildMdastToPmHandlers(
};
}
+
const blockUnknownHandler = (node: {
type: string;
position?: { start: { offset: number }; end: { offset: number } };
@@ -1098,6 +1106,7 @@ function buildMdastToPmHandlers(
return handlers as RemarkProseMirrorOptions['handlers'];
}
+
function buildPmToMdastHandlers(
schema: Schema,
freshness: FreshnessCheckerHolder,
diff --git a/packages/core/src/markdown/lint/applies-to.ts b/packages/core/src/markdown/lint/applies-to.ts
index fa0be9e86..b79e9aef7 100644
--- a/packages/core/src/markdown/lint/applies-to.ts
+++ b/packages/core/src/markdown/lint/applies-to.ts
@@ -1,3 +1,4 @@
+
import picomatch from 'picomatch';
import { SUPPORTED_DOC_EXTENSIONS } from '../../constants/doc-extensions.ts';
diff --git a/packages/core/src/markdown/lint/config-files.ts b/packages/core/src/markdown/lint/config-files.ts
index 312c9c74b..94b34dee1 100644
--- a/packages/core/src/markdown/lint/config-files.ts
+++ b/packages/core/src/markdown/lint/config-files.ts
@@ -1,3 +1,4 @@
+
const MARKDOWNLINT_JSON_CONFIG_FILES: ReadonlySet<string> = new Set([
'.markdownlint.json',
'.markdownlint.jsonc',
diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.ts
index 0ba33b7d8..e413367ef 100644
--- a/packages/core/src/markdown/lint/config-schemas.ts
+++ b/packages/core/src/markdown/lint/config-schemas.ts
@@ -38,6 +38,7 @@ const fullPluginShape = Object.fromEntries(
LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),
) as z.ZodRawShape;
+
export const LinterConfigSchema = z.object({
enabled: z.boolean(),
plugins: z.object(fullPluginShape),
diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.ts
index d48eea5e4..a51f2ffb0 100644
--- a/packages/core/src/markdown/lint/default-config.ts
+++ b/packages/core/src/markdown/lint/default-config.ts
@@ -6,6 +6,7 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSetting
MD013: false,
};
+
export function resolveMarkdownlintConfig(
rules: Record<string, MarkdownlintRuleSetting> | undefined,
): Configuration {
diff --git a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
index ef478e268..9c9542661 100644
--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
@@ -1,3 +1,4 @@
+
import { CANONICAL_SCHEMA_DIALECT_URIS, DEFAULT_SCHEMA_DIALECT } from './frontmatter-validate.ts';
export interface FrontmatterFieldConstraint {
diff --git a/packages/core/src/markdown/lint/frontmatter-validate.ts b/packages/core/src/markdown/lint/frontmatter-validate.ts
index 0d4c9a0df..b96d19182 100644
--- a/packages/core/src/markdown/lint/frontmatter-validate.ts
+++ b/packages/core/src/markdown/lint/frontmatter-validate.ts
@@ -1,3 +1,4 @@
+
import Ajv, { type ValidateFunction } from 'ajv';
import Ajv2019 from 'ajv/dist/2019.js';
import Ajv2020 from 'ajv/dist/2020.js';
diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.ts
index 00d08265a..48d260ed6 100644
--- a/packages/core/src/markdown/lint/index.ts
+++ b/packages/core/src/markdown/lint/index.ts
@@ -1,3 +1,4 @@
+
import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';
import type { LintDiagnostic } from './types.ts';
diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.ts
index 5e832aa19..be5871ed9 100644
--- a/packages/core/src/markdown/lint/plugins.ts
+++ b/packages/core/src/markdown/lint/plugins.ts
@@ -1,3 +1,4 @@
+
import { z } from 'zod';
import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';
import {
@@ -13,6 +14,7 @@ import {
type MarkdownlintSlice,
} from './types.ts';
+
const MarkdownlintRuleSettingSchema = z.union([
z.boolean(),
z.enum(MARKDOWNLINT_RULE_SEVERITIES),
diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.ts
index 3918e657c..833c3a727 100644
--- a/packages/core/src/markdown/lint/types.ts
+++ b/packages/core/src/markdown/lint/types.ts
@@ -1,3 +1,4 @@
+
export const LINT_PLUGIN_IDS = ['markdownlint', 'frontmatter'] as const;
export type LintPluginId = (typeof LINT_PLUGIN_IDS)[number];
@@ -71,6 +72,7 @@ export interface FrontmatterSlice {
schemas: ResolvedFrontmatterSchemaEntry[];
}
+
interface RuleOptionSpecBase {
key: string;
description: string;
diff --git a/packages/core/src/markdown/lint/validation-counts.ts b/packages/core/src/markdown/lint/validation-counts.ts
index 98238656e..437cc539a 100644
--- a/packages/core/src/markdown/lint/validation-counts.ts
+++ b/packages/core/src/markdown/lint/validation-counts.ts
@@ -1,3 +1,4 @@
+
export interface ValidationSourceCounts {
errorCount: number;
warningCount: number;
diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.ts
index a5b511f25..bd79424c7 100644
--- a/packages/core/src/markdown/math-promoter.ts
+++ b/packages/core/src/markdown/math-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Code, Root } from 'mdast';
import type { Math as MdastMath } from 'mdast-util-math';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.ts
index ed89371d0..00fbc0035 100644
--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts
+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, ElementContent, Properties } from 'hast';
import type { FootnoteDefinition, FootnoteReference } from 'mdast';
import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.ts
index 8ce2b2492..df788a80d 100644
--- a/packages/core/src/markdown/mdast-to-html.ts
+++ b/packages/core/src/markdown/mdast-to-html.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root as HastRoot, Text as HastText } from 'hast';
import type { Root as MdastRoot, Text as MdastText } from 'mdast';
import type { Handler } from 'mdast-util-to-hast';
diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.ts
index bfd7e3109..fa3cfcd86 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.ts
index 1a897fca8..17ed2b829 100644
--- a/packages/core/src/markdown/mermaid-promoter.ts
+++ b/packages/core/src/markdown/mermaid-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Code, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.ts
index d988f4b8b..4aa0490c4 100644
--- a/packages/core/src/markdown/parse-with-fallback.ts
+++ b/packages/core/src/markdown/parse-with-fallback.ts
@@ -168,6 +168,7 @@ export function parseRecursive(
}
}
+
interface VFilePlace {
offset?: number;
start?: { offset?: number };
@@ -186,6 +187,7 @@ function extractErrorOffset(err: unknown): number | undefined {
return undefined;
}
+
interface Region {
start: number;
end: number;
@@ -209,6 +211,7 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {
return null;
}
+
export interface TagEvent {
kind: 'open' | 'close' | 'self-close';
name: string;
@@ -355,6 +358,7 @@ function findFallbackRegion(src: string, errorOffset: number): Region {
return { start: blockStart, end: blockEnd };
}
+
interface SourceBlock {
src: string;
start: number;
@@ -452,6 +456,7 @@ function tryPerBlockFallback(
};
}
+
function wholeDocRawText(source: string): JSONContent {
return {
type: 'doc',
diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.ts
index e6ab4fd57..43d420187 100644
--- a/packages/core/src/markdown/parser-drop-closure.ts
+++ b/packages/core/src/markdown/parser-drop-closure.ts
@@ -1,3 +1,4 @@
+
export type DroppedTokenAdjudication =
| {
kind: 'format-dof-axis';
diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.ts
index 449e6f12f..5af2f05f5 100644
--- a/packages/core/src/markdown/pipeline.ts
+++ b/packages/core/src/markdown/pipeline.ts
@@ -1,3 +1,4 @@
+
import {
type FromProseMirrorOptions,
fromProseMirror,
diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.ts
index 91cdf658f..ccf06e94d 100644
--- a/packages/core/src/markdown/position-aware-join.ts
+++ b/packages/core/src/markdown/position-aware-join.ts
@@ -1,3 +1,4 @@
+
import type { Join } from 'mdast-util-to-markdown';
import type { Position } from 'unist';
import { isBlankLineParagraph } from './zero-emission-blocks.ts';
diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.ts
index 0f399d34c..e5b4c9eba 100644
--- a/packages/core/src/markdown/position-slice.ts
+++ b/packages/core/src/markdown/position-slice.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Root } from 'mdast';
import { visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
@@ -476,7 +477,8 @@ export function applyPositionSliceToNode(
const first = source[startOff];
if (first !== '[' && first !== '<' && !node.title) {
node.data.sourceStyle = 'gfm-autolink';
- } else if (first === '[') {
+ }
+ else if (first === '[') {
const slice = source.slice(startOff, endOff);
const closeBracketIdx = slice.lastIndexOf('](');
if (closeBracketIdx !== -1) {
diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
index db10fa54b..ca225ce9b 100644
--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, Root, Text } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
index 34068d103..3a2524a9a 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
index 93151d43b..2279a0189 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
index 188f02d83..a0f467c42 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
index 4ba2c3418..4e8542a21 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
index 1a74b1272..a3c96b24a 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
index de35e7b79..e95cf43d6 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
index b4be1b2ea..ffdb4d5b5 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
index 3c8d88b7c..e2a96d1a7 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.ts
index cf2c9da8e..0389575ac 100644
--- a/packages/core/src/markdown/resolve-image-url.ts
+++ b/packages/core/src/markdown/resolve-image-url.ts
@@ -1,3 +1,4 @@
+
import { isRelativeUrl } from './safe-url.ts';
function isDevDiagnosticContext(): boolean {
diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.ts
index 4d3250d3a..8be632ba4 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,3 +1,4 @@
+
export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;
const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');
diff --git a/packages/core/src/markdown/serialize-fidelity.test-helper.ts b/packages/core/src/markdown/serialize-fidelity.test-helper.ts
index 0dd54070e..96304e7a5 100644
--- a/packages/core/src/markdown/serialize-fidelity.test-helper.ts
+++ b/packages/core/src/markdown/serialize-fidelity.test-helper.ts
@@ -1,3 +1,4 @@
+
import type { JSONContent } from '@tiptap/core';
import type { Nodes } from 'mdast';
import { expect } from 'vitest';
diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.ts
index 7cac5b042..93798cf83 100644
--- a/packages/core/src/markdown/serialize-helpers.ts
+++ b/packages/core/src/markdown/serialize-helpers.ts
@@ -1,3 +1,4 @@
+
import type { Node as PmNode } from '@tiptap/pm/model';
import type {
MdxJsxAttribute,
diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.ts
index b012a5aff..8c08b7a04 100644
--- a/packages/core/src/markdown/single-dollar-math-promoter.ts
+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts
@@ -1,3 +1,4 @@
+
import type { PhrasingContent, Root, Text } from 'mdast';
import type { InlineMath } from 'mdast-util-math';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.ts
index 3e79f8cb6..959cc0bd2 100644
--- a/packages/core/src/markdown/to-markdown-handlers.ts
+++ b/packages/core/src/markdown/to-markdown-handlers.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parents } from 'mdast';
import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import type { Handle, Info, State } from 'mdast-util-to-markdown';
diff --git a/packages/core/src/markdown/underline-promoter.ts b/packages/core/src/markdown/underline-promoter.ts
index 0f1b0f27d..6e6d73400 100644
--- a/packages/core/src/markdown/underline-promoter.ts
+++ b/packages/core/src/markdown/underline-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import type { MdxJsxTextElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.ts
index 1a082bda7..932d7d2a8 100644
--- a/packages/core/src/markdown/unknown-mdast-guard.ts
+++ b/packages/core/src/markdown/unknown-mdast-guard.ts
@@ -1,3 +1,4 @@
+
import type { Root as MdastRoot } from 'mdast';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.ts
index d578476a7..ac9f5239b 100644
--- a/packages/core/src/markdown/whitespace-char-ref.ts
+++ b/packages/core/src/markdown/whitespace-char-ref.ts
@@ -1,3 +1,4 @@
+
const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([
[0x20, ' '],
[0x09, '\t'],
diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.ts
index 6dad26200..afd9936fe 100644
--- a/packages/core/src/markdown/wiki-link-micromark.ts
+++ b/packages/core/src/markdown/wiki-link-micromark.ts
@@ -17,6 +17,7 @@ declare module 'micromark-util-types' {
}
}
+
const CODE_BANG = 33; // !
const CODE_LBRACKET = 91; // [
const CODE_RBRACKET = 93; // ]
@@ -260,6 +261,7 @@ export function wikiLinkSyntax(): Extension {
};
}
+
function enterWikiLink(this: CompileContext, token: Token) {
this.enter(
{
@@ -385,6 +387,7 @@ export const wikiLinkToMarkdown: {
unsafe: [{ character: '[', inConstruct: ['phrasing'] }],
};
+
const MICROMARK_EXT = wikiLinkSyntax();
export function remarkWikiLink(this: Processor) {
diff --git a/packages/server/src/api-admission-composition.test.ts b/packages/server/src/api-admission-composition.test.ts
index d24568c43..a81e646bd 100644
--- a/packages/server/src/api-admission-composition.test.ts
+++ b/packages/server/src/api-admission-composition.test.ts
@@ -13,9 +13,9 @@ import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.
* invokes `onRequest` directly), but before this suite no test drove them
* through the actual listener + mcp-mount dispatch + api-extension chain —
* the exact layering the server refactor rewires. Assertions pin CURRENT
- * behavior, including behavior that is a known pre-auth exposure (read
- * routes answering under a rebound Host): if one of these starts failing,
- * the admission surface changed and the change must be intentional.
+ * behavior — including the read-posture hardening (reads are Host-gated in
+ * every mode, the no-auth compensating control): if one of these starts
+ * failing, the admission surface changed and the change must be intentional.
*/
let tmpRoot: string;
@@ -64,15 +64,16 @@ describe('/api admission over the composed listener — normal mode', () => {
expect(res.headers.get('vary')).toContain('Origin');
});
- test('read route ANSWERS under a rebound Host (current pre-auth exposure)', async () => {
- // Deliberate pin of today's posture: read-shaped /api routes are Origin-
- // gated but NOT Host/loopback-gated, so a DNS-rebound page's no-Origin
- // fetch can read them. The hosted-auth work changes this on purpose;
- // when it does, this assertion must be flipped in the same PR.
+ test('read route under a rebound Host is refused (read-posture hardening)', async () => {
+ // Flipped pin: reads are Host-gated in every mode now, same predicate the
+ // mutating gate uses (loopback names + bind literals + publicUrl host).
+ // A DNS-rebound page's no-Origin fetch can no longer read /api bodies —
+ // the no-auth compensating control.
const res = await rawRequest(normal.port, '/api/server-info', {
headers: { Host: 'evil.example' },
});
- expect(res.status).toBe(200);
+ expect(res.status).toBe(403);
+ expect(parseProblem(res.body).type).toBe('urn:ok:error:host-not-allowed');
});
test('mutating route under a rebound Host is refused', async () => {
@@ -128,6 +129,21 @@ describe('/api admission over the composed listener — normal mode', () => {
expect(res.status).toBe(204);
expect(res.headers.get('access-control-allow-methods')).toBe('GET, POST, PUT, DELETE, OPTIONS');
});
+
+ test('OPTIONS under a rebound Host still answers 204 — safe by CORS, not by the read gate', async () => {
+ // Documents the intentional gate ORDER: the OPTIONS short-circuit (step 3)
+ // returns 204 before the read gate (step 5), so a rebound-Host preflight is
+ // NOT 403'd. This is not a hole: no Origin was sent, so no
+ // Access-Control-Allow-Origin is reflected, and the rebound page's browser
+ // gets no CORS grant to read any follow-up response. (A present-but-foreign
+ // Origin is rejected by the Origin gate at step 3 instead.)
+ const res = await rawRequest(normal.port, '/api/server-info', {
+ method: 'OPTIONS',
+ headers: { Host: 'evil.example' },
+ });
+ expect(res.status).toBe(204);
+ expect(res.headers['access-control-allow-origin']).toBeUndefined();
+ });
});
describe('/api admission over the composed listener — ephemeral mode', () => {
diff --git a/packages/server/src/api-config.test.ts b/packages/server/src/api-config.test.ts
index a873b9169..e173d586b 100644
--- a/packages/server/src/api-config.test.ts
+++ b/packages/server/src/api-config.test.ts
@@ -121,17 +121,22 @@ describe('GET /api/config (desktop / worktree collab server)', () => {
}
});
- test('returns collabUrl null when the Host header is absent (deliberate divergence from ok ui)', async () => {
+ test('an absent Host header is refused at the read gate (flipped pin)', async () => {
const dir = mkdtempSync(join(tmpdir(), 'ok-config-'));
try {
- // No Host header at all. Unlike `ok ui` (which falls back to
- // `localhost:${resolvedPort}`), this handler advertises null and lets
- // the client fall back to a same-origin WS URL. Pin it so a future
- // change that silently adds a fallback is loud.
+ // Flipped pin (read-posture hardening): the universal /api read gate
+ // refuses a request carrying no Host header before the handler runs,
+ // so the handler's null-collabUrl advertisement branch (the former
+ // deliberate divergence from `ok ui`'s localhost fallback) is no
+ // longer reachable over the wire. This is NOT lost coverage: the
+ // null-on-absent-Host logic lives in the extracted
+ // `collabUrlFromRequestHeaders` and is pinned directly at the unit tier
+ // by `collab-bootstrap-url.test.ts` ("missing Host yields null"). There
+ // is no dead branch in the handler to delete — it just calls that fn.
const result = await call(buildExtension(dir), 'GET', '/api/config', {});
- expect(result.status).toBe(200);
- const body = JSON.parse(result.body) as { collabUrl: string | null };
- expect(body.collabUrl).toBeNull();
+ expect(result.status).toBe(403);
+ const body = JSON.parse(result.body) as { type: string };
+ expect(body.type).toBe('urn:ok:error:host-not-allowed');
} finally {
rmSync(dir, { recursive: true, force: true });
}
diff --git a/packages/server/src/api-document-composition.test.ts b/packages/server/src/api-document-composition.test.ts
index c9f46daf8..82be81b35 100644
--- a/packages/server/src/api-document-composition.test.ts
+++ b/packages/server/src/api-document-composition.test.ts
@@ -191,14 +191,15 @@ describe('document/pages group over the composed listener — served natively',
expect(res.headers.get('access-control-allow-methods')).toBe('GET, POST, PUT, DELETE, OPTIONS');
});
- test('read posture parity: a ported route ANSWERS under a rebound Host in normal mode', async () => {
- // Same deliberate pin as the earlier groups' suites: read-shaped routes
- // are Origin-gated but NOT Host/loopback-gated. When the hosted-auth work
- // flips that posture, this assertion flips in the same PR.
+ test('read posture parity: a ported route under a rebound Host is refused in normal mode', async () => {
+ // Flipped pin (read-posture hardening): reads share the mutating gate's
+ // Host predicate in every mode, so a rebound Host is refused on ported
+ // reads too.
const res = await rawRequest(server.port, '/api/pages', {
headers: { Host: 'evil.example' },
});
- expect(res.status).toBe(200);
+ expect(res.status).toBe(403);
+ expect(parseProblem(res.body).type).toBe('urn:ok:error:host-not-allowed');
});
test('ephemeral mode Host-gates the ported reads too', async () => {
diff --git a/packages/server/src/api-link-graph-composition.test.ts b/packages/server/src/api-link-graph-composition.test.ts
index 743d9c595..b63ddc4f0 100644
--- a/packages/server/src/api-link-graph-composition.test.ts
+++ b/packages/server/src/api-link-graph-composition.test.ts
@@ -116,14 +116,15 @@ describe('link/graph group over the composed listener — served natively', () =
expect(body.detail ?? body.title).toContain('Proxied request refused');
});
- test('read posture parity: a ported route ANSWERS under a rebound Host in normal mode', async () => {
- // Same deliberate pin as the legacy-dispatch suite: read-shaped routes
- // are Origin-gated but NOT Host/loopback-gated. When the hosted-auth work
- // flips that posture, this assertion flips in the same PR.
+ test('read posture parity: a ported route under a rebound Host is refused in normal mode', async () => {
+ // Flipped pin (read-posture hardening): reads share the mutating gate's
+ // Host predicate in every mode, so a rebound Host is refused on ported
+ // reads too.
const res = await rawRequest(normal.port, '/api/backlinks?docName=beta', {
headers: { Host: 'evil.example' },
});
- expect(res.status).toBe(200);
+ expect(res.status).toBe(403);
+ expect(parseProblem(res.body).type).toBe('urn:ok:error:host-not-allowed');
});
test('ephemeral mode Host-gates the ported reads too', async () => {
diff --git a/packages/server/src/api-metrics-composition.test.ts b/packages/server/src/api-metrics-composition.test.ts
index 3fe9228fa..897ae446e 100644
--- a/packages/server/src/api-metrics-composition.test.ts
+++ b/packages/server/src/api-metrics-composition.test.ts
@@ -144,14 +144,15 @@ describe('metrics group over the composed listener — served natively', () => {
expect(body.detail ?? body.title).toContain('Proxied request refused');
});
- test('read posture parity: an UNGATED read ANSWERS under a rebound Host in normal mode', async () => {
- // Same deliberate pin as the link-graph suite: reads without an inline
- // gate are Origin-gated but NOT Host/loopback-gated. When the hosted-auth
- // work flips that posture, this assertion flips in the same PR.
+ test('read posture parity: a read WITHOUT an inline gate is refused under a rebound Host', async () => {
+ // Flipped pin (read-posture hardening): the pipeline Host-gates every
+ // /api read in normal mode too, so routes without an inline gate are
+ // covered by the shared choke point.
const res = await rawRequest(server.port, '/api/metrics/reconciliation', {
headers: { Host: 'evil.example' },
});
- expect(res.status).toBe(200);
+ expect(res.status).toBe(403);
+ expect(parseProblem(res.body).type).toBe('urn:ok:error:host-not-allowed');
});
test('ephemeral mode Host-gates the ported reads too', async () => {
diff --git a/packages/server/src/asset-serve-middleware.integration.test.ts b/packages/server/src/asset-serve-middleware.integration.test.ts
index 0038e3448..35b833b76 100644
--- a/packages/server/src/asset-serve-middleware.integration.test.ts
+++ b/packages/server/src/asset-serve-middleware.integration.test.ts
@@ -24,7 +24,7 @@
*/
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { createServer, type Server } from 'node:http';
+import { createServer, request as httpRequest, type Server } from 'node:http';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import {
@@ -36,6 +36,7 @@ import sirv from 'sirv';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import { createAssetServeMiddleware } from './asset-serve-middleware.ts';
import { createContentFilter } from './content-filter.ts';
+import { buildIngressPolicy } from './ingress-policy.ts';
import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
interface Harness {
@@ -59,6 +60,7 @@ async function startHarness(contentDir: string): Promise<Harness> {
inlineExtensions: INLINE_RENDERABLE_EXTENSIONS,
assetExtensions: ASSET_EXTENSIONS,
blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,
+ ingressPolicy: buildIngressPolicy({}),
});
const server: Server = createServer((req, res) => {
@@ -358,6 +360,56 @@ describe('asset-serve middleware (narrow integration)', () => {
});
});
+ describe('Content-serve ingress gate (DNS-rebinding defense)', () => {
+ // Forged Host must go over node:http — undici's fetch silently drops a
+ // caller-set Host header. Same mechanism the workspace host-gate tests use.
+ function getWithHost(path: string, host: string): Promise<{ status: number; body: string }> {
+ return new Promise((resolve, reject) => {
+ const url = new URL(path, harness.baseURL);
+ const req = httpRequest(
+ { host: url.hostname, port: url.port, path: url.pathname, headers: { Host: host } },
+ (res) => {
+ let body = '';
+ res.on('data', (chunk) => {
+ body += chunk;
+ });
+ res.on('end', () => resolve({ status: res.statusCode ?? 0, body }));
+ },
+ );
+ req.on('error', reject);
+ req.end();
+ });
+ }
+
+ test('a rebound Host on an existing asset is refused BEFORE the disk read', async () => {
+ const res = await getWithHost('/docs/photo.png', 'evil.example.com');
+ expect(res.status).toBe(403);
+ expect((JSON.parse(res.body) as { type?: string }).type).toBe(
+ 'urn:ok:error:host-not-allowed',
+ );
+ });
+
+ test('a rebound Host on a markdown doc path is refused the same way', async () => {
+ const res = await getWithHost('/docs/guide.md', 'evil.example.com');
+ expect(res.status).toBe(403);
+ expect((JSON.parse(res.body) as { type?: string }).type).toBe(
+ 'urn:ok:error:host-not-allowed',
+ );
+ });
+
+ test('a rebound Host on a NON-content path still falls through (SPA shell stays ungated)', async () => {
+ const res = await getWithHost('/some/deep-link', 'evil.example.com');
+ expect(res.status).toBe(200);
+ expect(res.body).toContain('spa fallback sentinel');
+ });
+
+ test('a loopback Host keeps serving the asset (legit traffic unaffected)', async () => {
+ const url = new URL('/docs/photo.png', harness.baseURL);
+ const res = await getWithHost('/docs/photo.png', `127.0.0.1:${url.port}`);
+ expect(res.status).toBe(200);
+ });
+ });
+
describe('Regression guards for the serve-side contract', () => {
test('query strings are stripped from path resolution', async () => {
const res = await fetch(`${harness.baseURL}/docs/doc.pdf?t=42`);
diff --git a/packages/server/src/asset-serve-middleware.test.ts b/packages/server/src/asset-serve-middleware.test.ts
index a685cb0d6..b971927e7 100644
--- a/packages/server/src/asset-serve-middleware.test.ts
+++ b/packages/server/src/asset-serve-middleware.test.ts
@@ -18,12 +18,13 @@ import {
createAssetServeMiddleware,
type SirvLikeMiddleware,
} from './asset-serve-middleware.ts';
+import { buildIngressPolicy } from './ingress-policy.ts';
-function makeReq(url: string): IncomingMessage {
+function makeReq(url: string, host = 'localhost'): IncomingMessage {
const readable = Readable.from(Buffer.alloc(0)) as unknown as IncomingMessage;
readable.method = 'GET';
readable.url = url;
- readable.headers = { host: 'localhost' };
+ readable.headers = { host };
return readable;
}
@@ -32,10 +33,17 @@ interface CapturedResponse {
headers: Record<string, string>;
headersSent: boolean;
ended: boolean;
+ body: string;
}
function makeRes(): { res: ServerResponse; captured: CapturedResponse } {
- const captured: CapturedResponse = { status: 0, headers: {}, headersSent: false, ended: false };
+ const captured: CapturedResponse = {
+ status: 0,
+ headers: {},
+ headersSent: false,
+ ended: false,
+ body: '',
+ };
const res = {
setHeader(name: string, value: string) {
captured.headers[name] = value;
@@ -48,8 +56,9 @@ function makeRes(): { res: ServerResponse; captured: CapturedResponse } {
captured.headersSent = true;
if (headers) Object.assign(captured.headers, headers);
},
- end(_body?: string) {
+ end(body?: string) {
captured.ended = true;
+ if (typeof body === 'string') captured.body = body;
},
get headersSent() {
return captured.headersSent;
@@ -94,6 +103,7 @@ function buildMiddleware(sirv: SirvLikeMiddleware, filter: AssetServeFilter = ad
inlineExtensions: INLINE,
assetExtensions: ASSETS,
blocklistExtensions: BLOCKLIST,
+ ingressPolicy: buildIngressPolicy({}),
});
}
@@ -122,6 +132,86 @@ describe('createAssetServeMiddleware', () => {
});
});
+ describe('content-serve ingress gate (policy item 0)', () => {
+ test('a rebound Host on a servable path is refused without touching sirv', () => {
+ let sirvInvoked = false;
+ const sirvSpy: SirvLikeMiddleware = (_req, _res, fallback) => {
+ sirvInvoked = true;
+ fallback();
+ };
+ const middleware = buildMiddleware(sirvSpy);
+ const { res, captured } = makeRes();
+ middleware(makeReq('/photo.png', 'evil.example'), res, () => {});
+ expect(captured.status).toBe(403);
+ // Assert the error-type URN, not just the status — a swap between the
+ // host and peer branches would otherwise pass at the unit tier.
+ expect(JSON.parse(captured.body).type).toBe('urn:ok:error:host-not-allowed');
+ expect(sirvInvoked).toBe(false);
+ // Refused before any serve-side header work — nosniff/disposition are
+ // the serve path's headers, not the refusal's.
+ expect(captured.headers['Content-Disposition']).toBeUndefined();
+ });
+
+ test('a rebound Host on a doc path (.md) is refused the same way', () => {
+ const middleware = buildMiddleware(sirvServes);
+ const { res, captured } = makeRes();
+ middleware(makeReq('/notes.md', 'evil.example'), res, () => {});
+ expect(captured.status).toBe(403);
+ expect(JSON.parse(captured.body).type).toBe('urn:ok:error:host-not-allowed');
+ });
+
+ test('a non-loopback TCP peer on a servable path is refused with loopback-required', () => {
+ // Peer branch (distinct from the Host branch): a production socket
+ // whose remoteAddress is non-loopback fails `isPeerAdmitted` under the
+ // loopback-only default policy. `makeReq`'s Readable carries no socket
+ // (peer check skipped), so attach one to exercise the branch.
+ let sirvInvoked = false;
+ const sirvSpy: SirvLikeMiddleware = (_req, _res, fallback) => {
+ sirvInvoked = true;
+ fallback();
+ };
+ const middleware = buildMiddleware(sirvSpy);
+ const { res, captured } = makeRes();
+ const req = makeReq('/photo.png', 'localhost');
+ (req as unknown as { socket: { remoteAddress: string } }).socket = {
+ remoteAddress: '203.0.113.7',
+ };
+ middleware(req, res, () => {});
+ expect(captured.status).toBe(403);
+ // Peer branch → loopback-required (distinct URN from the Host branch).
+ expect(JSON.parse(captured.body).type).toBe('urn:ok:error:loopback-required');
+ expect(sirvInvoked).toBe(false);
+ });
+
+ test('a rebound Host on a NON-servable path still falls through ungated (SPA shell)', () => {
+ let nextCalled = false;
+ const middleware = buildMiddleware(sirvServes);
+ const { res } = makeRes();
+ middleware(makeReq('/deep-link', 'evil.example'), res, () => {
+ nextCalled = true;
+ });
+ expect(nextCalled).toBe(true);
+ });
+
+ test('a rebound Host on an ignored path falls through ungated too', () => {
+ let nextCalled = false;
+ const middleware = buildMiddleware(sirvServes, excludeAll);
+ const { res } = makeRes();
+ middleware(makeReq('/photo.png', 'evil.example'), res, () => {
+ nextCalled = true;
+ });
+ expect(nextCalled).toBe(true);
+ });
+
+ test('a loopback Host serves normally through the gate', () => {
+ const middleware = buildMiddleware(sirvServes);
+ const { res, captured } = makeRes();
+ middleware(makeReq('/photo.png', '127.0.0.1:5173'), res, () => {});
+ expect(captured.status).toBe(200);
+ expect(captured.headers['Content-Disposition']).toBe('inline');
+ });
+ });
+
describe('Content-Disposition dispatch', () => {
test('INLINE_RENDERABLE extension gets `inline` disposition', () => {
const middleware = buildMiddleware(sirvServes);
diff --git a/packages/server/src/asset-serve-middleware.ts b/packages/server/src/asset-serve-middleware.ts
index dc86e4913..181778885 100644
--- a/packages/server/src/asset-serve-middleware.ts
+++ b/packages/server/src/asset-serve-middleware.ts
@@ -13,6 +13,25 @@
* against a tmpdir (narrow-integration tier).
*
* Policy:
+ * 0. Once a request is known to be a content-serve attempt (it survives
+ * the fall-through checks in item 1), it must pass the shared ingress
+ * peer + Host predicates — the read half of the DNS-rebinding defense
+ * for the static surface, mirroring the `/api` pipeline's read gate. A
+ * rebound page (loopback TCP peer, attacker-controlled Host) is
+ * refused BEFORE any disk read. What is gated is exactly the
+ * content-serve set: `.md`/`.mdx` and every `ASSET_EXTENSIONS` member —
+ * which INCLUDES `.html`/`.htm` (author HTML is servable content). The
+ * extension-LESS SPA-shell path (`GET /`, deep-links) and Vite-owned
+ * URLs fall through UNGATED (item 1's not-a-servable-extension bail):
+ * the shell is public bundle code and a rebound attacker serves their
+ * own page anyway, so gating it risks breaking legitimate loads for
+ * zero security gain. One caveat: `ok ui` rewrites `GET /` to
+ * `/index.html` BEFORE this middleware, so its shell root IS gated
+ * here — acceptable because `ok ui` is a loopback-only sidecar (its
+ * `/api` gate admits loopback Hosts only); the exposable surface is
+ * `ok start`, where `GET /` stays extension-less and ungated. Origin is
+ * intentionally NOT checked — no-cors `<img>` / CSS loads omit it, and
+ * the Host check alone closes the rebinding content-exfil vector.
* 1. Fall through to `next()` (so the next middleware — Vite's static
* serve, then SPA fallback — can handle the URL) when EITHER:
* (a) the content filter marks the path ignored (`isPathIgnored` —
@@ -57,6 +76,13 @@
import type { IncomingMessage, ServerResponse } from 'node:http';
import { extname } from 'node:path';
import { SANDBOXED_HTML_EXTENSIONS } from '@inkeep/open-knowledge-core';
+import { errorResponse } from './http/error-response.ts';
+import {
+ HOST_NOT_ADMITTED_REMEDIATION,
+ type IngressPolicy,
+ isHostAdmitted,
+ isPeerAdmitted,
+} from './ingress-policy.ts';
import { classifyAssetDisposition } from './services/asset-classification.ts';
/**
@@ -103,13 +129,27 @@ interface AssetServeMiddlewareDeps {
* so the serve surface refuses what the click surface refuses.
*/
blocklistExtensions: ReadonlySet<string>;
+ /**
+ * The boot-built ingress policy driving the content-serve peer + Host
+ * gate (policy item 0). Required — every consumer supplies the one
+ * policy its surface runs under, so a new serve surface cannot silently
+ * skip the gate. Surfaces without a resolved runtime (the Vite dev
+ * plugin) pass the loopback-only default (`buildIngressPolicy({})`).
+ */
+ ingressPolicy: IngressPolicy;
}
export function createAssetServeMiddleware(
deps: AssetServeMiddlewareDeps,
): (req: IncomingMessage, res: ServerResponse, next: () => void) => void {
- const { contentFilter, contentSirv, inlineExtensions, assetExtensions, blocklistExtensions } =
- deps;
+ const {
+ contentFilter,
+ contentSirv,
+ inlineExtensions,
+ assetExtensions,
+ blocklistExtensions,
+ ingressPolicy,
+ } = deps;
return (req, res, next) => {
// Malformed percent-encoding (`/%`, `/%E0%A4`) throws URIError; treat
@@ -140,6 +180,25 @@ export function createAssetServeMiddleware(
// hence the CSP sandbox below, matching `handleAsset`.
if (!rel || contentFilter.isPathIgnored(rel) || (!isDocExt && !assetExtensions.has(ext)))
return next();
+ // Content-serve gate (policy item 0). Fires before any header or disk
+ // work so a refused request observes nothing — including whether the
+ // file exists. A missing socket only occurs on synthetic test requests
+ // (matches the `/api` pipeline's convention); the Host check still runs
+ // there, so the rebinding defense stays meaningful on every path.
+ const peerAddress = req.socket?.remoteAddress;
+ if (peerAddress !== undefined && !isPeerAdmitted(peerAddress, ingressPolicy)) {
+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
+ handler: 'content-asset-gate',
+ });
+ return;
+ }
+ if (!isHostAdmitted(req.headers.host, ingressPolicy)) {
+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
+ handler: 'content-asset-gate',
+ detail: HOST_NOT_ADMITTED_REMEDIATION,
+ });
+ return;
+ }
res.setHeader('X-Content-Type-Options', 'nosniff');
// Shared with `/api/asset`: one extension → disposition/CSP policy for
// both serve surfaces (rationale lives with the classifier).
diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.ts
index a2f528f8b..223fc3d53 100644
--- a/packages/server/src/boot.ts
+++ b/packages/server/src/boot.ts
@@ -928,6 +928,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {
inlineExtensions: INLINE_RENDERABLE_EXTENSIONS,
assetExtensions: ASSET_EXTENSIONS,
blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,
+ ingressPolicy,
})
: undefined;
diff --git a/packages/server/src/collaboration-host.ts b/packages/server/src/collaboration-host.ts
index 92a0e39c8..06df8d8aa 100644
--- a/packages/server/src/collaboration-host.ts
+++ b/packages/server/src/collaboration-host.ts
@@ -331,11 +331,14 @@ export function createCollaborationHost(options: CollaborationHostOptions): Coll
//
// (2) Peer + Host admission (`admitted()`) — only when EXPOSED (legacy
// `--remote` OR `allowExternal`). Pure-local keeps its historical
- // ungated posture on this axis; the general loopback+Host-on-everything
- // read-posture flip is a separate PR. Under consent the loopback bind no
- // longer implies a loopback peer, so `admitted()` (loopback + bind
- // literals + publicUrl, identical to the HTTP API gate) keeps direct-IP
- // access matching what `/api` accepts.
+ // ungated posture on this axis — a deliberate carve-out from the
+ // read-posture hardening that Host-gates `/api` reads and content-
+ // asset serving in every mode: WS upgrades are not reachable from a
+ // rebound page without an Origin header, and axis (1) refuses the
+ // foreign-Origin shape unconditionally. Under consent the loopback
+ // bind no longer implies a loopback peer, so `admitted()` (loopback +
+ // bind literals + publicUrl, identical to the HTTP API gate) keeps
+ // direct-IP access matching what `/api` accepts.
const foreignOrigin =
req.headers.origin !== undefined && !isOriginAdmitted(req.headers.origin, ingressPolicy);
const exposed = ingressPolicy.legacyRemote !== undefined || ingressPolicy.allowExternal;
diff --git a/packages/server/src/handoff-api.test.ts b/packages/server/src/handoff-api.test.ts
index 0ee81030f..e3e2ca4a5 100644
--- a/packages/server/src/handoff-api.test.ts
+++ b/packages/server/src/handoff-api.test.ts
@@ -471,6 +471,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
const hocuspocus = new Hocuspocus({ quiet: true });
const sessionManager = new AgentSessionManager(hocuspocus);
+ const { buildIngressPolicy } = await import('./ingress-policy.ts');
const ext = createApiExtension({
hocuspocus,
sessionManager,
@@ -481,6 +482,22 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
// Deterministic mock response: claude + cursor installed, codex not.
return scheme === 'claude' || scheme === 'cursor';
},
+ // Declared remote deployment: the /api read gate admits only loopback +
+ // bind literals + the publicUrl host, so the remote-web capability-tier
+ // Hosts below must be declared names to reach the handler at all (an
+ // undeclared foreign Host is refused at the gate; see the gate test).
+ ingressPolicy: buildIngressPolicy({
+ serverRuntime: {
+ port: undefined,
+ bind: ['127.0.0.1', '192.168.1.100'],
+ publicUrl: 'http://example.com:5173',
+ publicUrlSource: 'server',
+ allowExternal: true,
+ openBrowser: false,
+ idleShutdown: 'off',
+ loopbackOnly: false,
+ },
+ }),
});
const { createServer } = await import('node:http');
@@ -570,7 +587,10 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
// (remote-web — return all-installed and let the OS protocol-dispatch
// dialog be the truth signal). The remote-web case is normally reached via
// SSH tunnels / reverse proxies where the connection still terminates on
- // loopback; these tests simulate it directly with a forged Host header.
+ // loopback. Since the read-posture hardening, a non-loopback Host reaches
+ // the handler only when the deployment DECLARES it (`server.publicUrl` /
+ // `server.bind`) — the rig's policy above declares both test Hosts, and an
+ // undeclared one is pinned as refused at the gate below.
test('remote-web (Host: example.com) → all-true and probe NOT called', async () => {
// Cross-origin Origin is rejected by checkLocalOpSecurity, so only the Host
@@ -600,6 +620,17 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
expect(probeCalls).toEqual({ claude: 1, codex: 1, cursor: 1 });
});
+ test('an UNDECLARED foreign Host is refused at the read gate before the handler', async () => {
+ // Read-posture hardening boundary: without a declaration the server
+ // cannot distinguish an SSH-tunnel user from a DNS-rebound page, so the
+ // gate refuses before any capability-tier logic (or probe) runs.
+ const res = await getWithHostHeader(port, '/api/installed-agents', 'evil.example:5173');
+ expect(res.status).toBe(403);
+ const body = (await res.json()) as { type?: string };
+ expect(body.type).toBe('urn:ok:error:host-not-allowed');
+ expect(probeCalls).toEqual({});
+ });
+
test('remote-web requests are NOT cached against later local-web requests', async () => {
// Capability-tier short-circuits without populating the cache, so a
// following local-web request still triggers the real probe.
diff --git a/packages/server/src/http/admit-request-surface.test.ts b/packages/server/src/http/admit-request-surface.test.ts
index 26222bbdc..e45dff9ad 100644
--- a/packages/server/src/http/admit-request-surface.test.ts
+++ b/packages/server/src/http/admit-request-surface.test.ts
@@ -102,8 +102,11 @@ describe('admitRequestSurface under allowExternal consent', () => {
});
test('a pure-local policy (no exposure) does NOT Host-gate the surface here', () => {
- // Gate 2 only runs under exposure; pure-local keeps its historical
- // origin-only read posture (the general read-posture flip is a separate PR).
+ // Gate 2 only runs under exposure. Pure-local rebinding defense lives
+ // with the legs behind this prelude instead: the `/api` pipeline read
+ // gate, the content-serve gate in `asset-serve-middleware.ts`, and the
+ // unconditional `/mcp` gate. The SPA shell (the remaining surface) is
+ // deliberately ungated — public bundle code.
const local = buildIngressPolicy({});
const { res, status } = fakeRes();
expect(admitRequestSurface(req('evil.example'), res, local, 'test')).toBe(true);
diff --git a/packages/server/src/http/api-pipeline.test.ts b/packages/server/src/http/api-pipeline.test.ts
index 580294388..fa3894cf9 100644
--- a/packages/server/src/http/api-pipeline.test.ts
+++ b/packages/server/src/http/api-pipeline.test.ts
@@ -256,7 +256,7 @@ describe('natively-mounted /api routes run the shared admission pipeline', () =>
}
});
- test('a mutating native route under a rebound Host is refused; a read route answers', async () => {
+ test('native routes under a rebound Host are refused — mutating AND read', async () => {
const rig = await bootNativeRig();
try {
const refused = await rawRequest(rig.port, '/api/native-mutating', {
@@ -265,11 +265,13 @@ describe('natively-mounted /api routes run the shared admission pipeline', () =>
expect(refused.status).toBe(403);
expect(parseProblem(refused.body).type).toBe('urn:ok:error:host-not-allowed');
- // Read posture parity: Origin-gated but NOT Host-gated in normal mode.
+ // Flipped pin (read-posture hardening): reads share the mutating
+ // gate's Host predicate in normal mode too.
const read = await rawRequest(rig.port, '/api/native-ping', {
headers: { Host: 'evil.example' },
});
- expect(read.status).toBe(200);
+ expect(read.status).toBe(403);
+ expect(parseProblem(read.body).type).toBe('urn:ok:error:host-not-allowed');
const allowed = await rawRequest(rig.port, '/api/native-mutating', {
headers: { Host: 'localhost' },
diff --git a/packages/server/src/http/api-pipeline.ts b/packages/server/src/http/api-pipeline.ts
index 4940475c2..cd45df923 100644
--- a/packages/server/src/http/api-pipeline.ts
+++ b/packages/server/src/http/api-pipeline.ts
@@ -24,7 +24,9 @@
* so even gate-rejected responses carry the `x-request-id` echo
* 3. origin-allowlist CORS with verbatim ACAO reflection + OPTIONS 204
* 4. mutating-route loopback + workspace-Host gate (DNS-rebinding defense)
- * 5. ephemeral-mode loopback + workspace-Host gate on every `/api/*` read
+ * 5. loopback + workspace-Host gate on EVERY `/api/*` request — the read
+ * half of the DNS-rebinding defense, in all modes (the no-auth
+ * compensating control; ephemeral mode pioneered it)
* 6. OTel server span wrapping dispatch, the unmatched-route 404, and the
* duration histogram
*
@@ -48,6 +50,7 @@ import {
import { recordEmbedProbe } from '../embed-probe.ts';
import {
buildIngressPolicy,
+ HOST_NOT_ADMITTED_REMEDIATION,
type IngressPolicy,
isHostAdmitted,
isOriginAdmitted,
@@ -98,7 +101,11 @@ export interface ApiPipelineOptions {
* (test rigs) ⇒ the loopback-only default policy.
*/
policy?: IngressPolicy;
- /** No-project ephemeral single-file mode — gates EVERY `/api/*` request. */
+ /**
+ * No-project ephemeral single-file mode. The peer + Host gate now covers
+ * every `/api/*` request in all modes; this flag only selects the
+ * historical `api-ephemeral-gate` telemetry tag over `api-read-gate`.
+ */
ephemeral?: boolean;
table: ApiRouteTable;
}
@@ -312,36 +319,41 @@ export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPi
if (!isAllowedWorkspaceHostHeader(request.headers.host)) {
errorResponse(response, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
handler: 'api-mutating-gate',
+ detail: HOST_NOT_ADMITTED_REMEDIATION,
});
return true;
}
}
- // No-project ephemeral single-file mode (`ok <file>`) sets contentDir to
- // the opened file's PARENT — often a user-data dir (~/Downloads,
- // ~/Documents). Several read routes (`/api/asset`, `/api/asset-text`,
- // `/api/document`) return bytes under contentDir bounded only by
- // `isWithinContentDir`, NOT by the single-file content scope (which is
- // enforced at the indexing/listing layer, not the byte-read path). So
- // without a host gate a DNS-rebound page could exfiltrate sibling files.
- // Apply the same loopback + workspace-host check the mutating gate uses to
- // EVERY `/api/*` request in ephemeral mode — one choke point, so future
- // read routes inherit it rather than each needing its own gate. Project /
- // desktop modes (`ephemeral` falsy) keep their prior origin-only posture
- // for reads (the user chose the served root there); this mirrors the
- // ephemeral-scoped content-asset gate in `mcp-mount.ts`, which covers the
- // non-`/api/` static-serve path.
- if (ephemeral && url.startsWith('/api/')) {
+ // Read half of the DNS-rebinding defense — the no-auth compensating
+ // control. Reads used to be Origin-gated only outside ephemeral mode, but
+ // a rebound page's GET carries no Origin (a simple same-origin fetch) and
+ // presents the attacker's Host, so without a Host gate the response bytes
+ // (document content, sibling files) are readable cross-origin. Apply the
+ // same loopback + workspace-Host check the mutating gate uses to EVERY
+ // `/api/*` request — one choke point, so future read routes inherit it
+ // rather than each needing its own gate. Ephemeral single-file mode
+ // (`ok <file>` — contentDir is the opened file's PARENT, often a
+ // user-data dir like ~/Downloads) has gated all of `/api` this way since
+ // the mode shipped; it keeps its historical `api-ephemeral-gate` handler
+ // tag so its counters stay continuous, while normal-mode refusals tag
+ // `api-read-gate` so the universalized posture's fire rate is observable
+ // in isolation. Native clients (curl, MCP) are unaffected: they dial an
+ // admitted name (loopback, bind literal, or publicUrl host), and Origin
+ // logic is untouched.
+ if (url.startsWith('/api/')) {
+ const gateHandler = ephemeral ? 'api-ephemeral-gate' : 'api-read-gate';
const peerAddress = request.socket?.remoteAddress;
if (peerAddress !== undefined && !isPeerAdmitted(peerAddress, policy)) {
errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
- handler: 'api-ephemeral-gate',
+ handler: gateHandler,
});
return true;
}
if (!isAllowedWorkspaceHostHeader(request.headers.host)) {
errorResponse(response, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
- handler: 'api-ephemeral-gate',
+ handler: gateHandler,
+ detail: HOST_NOT_ADMITTED_REMEDIATION,
});
return true;
}
diff --git a/packages/server/src/http/http-app.ts b/packages/server/src/http/http-app.ts
index b81f504a3..e684f9c97 100644
--- a/packages/server/src/http/http-app.ts
+++ b/packages/server/src/http/http-app.ts
@@ -97,9 +97,12 @@ export function admitRequestSurface(
// `/mcp`, `/api/*`, the static shell, and project-mode content assets. The
// predicate is the consolidated one (loopback + bind literals + publicUrl),
// identical to the `/api` pipeline gate, so direct-IP access to the shell/
- // content matches what the API admits. Pure-local (no exposure) keeps its
- // historical origin-only read posture here; the general loopback+Host-on-
- // all-reads flip is a separate PR.
+ // content matches what the API admits. Pure-local (no exposure) skips this
+ // SURFACE-wide gate on purpose — the read-sensitive legs behind it carry
+ // their own always-on Host gates (the `/api` pipeline read gate, the
+ // content-serve gate in `asset-serve-middleware.ts`, the unconditional
+ // `/mcp` gate), while the SPA shell stays deliberately ungated: it is
+ // public bundle code, and a rebound attacker serves their own page anyway.
if (policy.legacyRemote !== undefined || policy.allowExternal) {
const host = Array.isArray(req.headers.host) ? req.headers.host[0] : req.headers.host;
if (!isPeerAdmitted(req.socket.remoteAddress, policy) || !isHostAdmitted(host, policy)) {
diff --git a/packages/server/src/ingress-policy.ts b/packages/server/src/ingress-policy.ts
index ad0fc1326..53812c60a 100644
--- a/packages/server/src/ingress-policy.ts
+++ b/packages/server/src/ingress-policy.ts
@@ -41,6 +41,17 @@ import {
type ResolvedRemoteAccess,
} from './remote-access.ts';
+/**
+ * Remediation detail for a `host-not-allowed` refusal. The read gate now fires
+ * in normal mode, so a legitimate operator can trip it (a reverse proxy that
+ * preserves the client Host, a `.local`/hosts-file alias pointing at a loopback
+ * bind). The bare title names no fix; this detail tells them which config key
+ * admits the host without reading source. Shared across every gate that emits
+ * `host-not-allowed` so the guidance never drifts between sites.
+ */
+export const HOST_NOT_ADMITTED_REMEDIATION =
+ 'Add this host to server.bind or set server.publicUrl to it, then restart. Loopback (localhost/127.0.0.1/[::1]) is always admitted.';
+
export interface IngressPolicy {
/**
* Exposure consent (`server.allowExternal`, scope-correctly resolved).
diff --git a/packages/server/src/mcp-mount.test.ts b/packages/server/src/mcp-mount.test.ts
index 86cb83aa6..bed701c29 100644
--- a/packages/server/src/mcp-mount.test.ts
+++ b/packages/server/src/mcp-mount.test.ts
@@ -13,6 +13,7 @@ import sirv from 'sirv';
import { afterEach, describe, expect, test, vi } from 'vitest';
import { WebSocket } from 'ws';
import { createAssetServeMiddleware } from './asset-serve-middleware.ts';
+import { buildIngressPolicy } from './ingress-policy.ts';
import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';
import type { McpHttpHandler } from './mcp-http.ts';
import {
@@ -509,7 +510,9 @@ describe('mountMcpAndApi content-asset middleware', () => {
// file's parent — often a user-data dir. The content-asset surface must carry
// the same loopback + workspace-host gate the `/mcp` leg uses so a DNS-rebound
// or non-loopback caller can't read that dir. Project / desktop modes
-// (`ephemeral` unset) keep serving assets unchanged.
+// (`ephemeral` unset) are covered by the in-middleware content-serve gate
+// (read-posture hardening) — same Host predicate, fired only on actual
+// content-serve attempts.
describe('mountMcpAndApi ephemeral content-asset gate', () => {
const tmpDirs: string[] = [];
@@ -534,6 +537,7 @@ describe('mountMcpAndApi ephemeral content-asset gate', () => {
inlineExtensions: INLINE_RENDERABLE_EXTENSIONS,
assetExtensions: ASSET_EXTENSIONS,
blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,
+ ingressPolicy: buildIngressPolicy({}),
}),
});
const port = await getFreeLoopbackPort();
@@ -548,21 +552,25 @@ describe('mountMcpAndApi ephemeral content-asset gate', () => {
expect(res.status).toBe(200);
});
- test('ephemeral: a rebound Host header is rejected with 403 loopback-required', async () => {
+ test('ephemeral: a rebound Host header is rejected with 403 host-not-allowed', async () => {
const { port } = await startAssets(true);
// Loopback TCP peer (127.0.0.1) but an attacker-controlled Host — the
- // DNS-rebinding shape. The Host gate rejects it before sirv reads the file.
+ // DNS-rebinding shape. The peer check passes (loopback), the Host check
+ // fails, so the split gate reports `host-not-allowed` (not the misleading
+ // `loopback-required` the old combined OR emitted).
const res = await getWithHost(port, '/secret.png', 'evil.example.com');
expect(res.status).toBe(403);
- expect((JSON.parse(res.body) as { type?: string }).type).toBe('urn:ok:error:loopback-required');
+ expect((JSON.parse(res.body) as { type?: string }).type).toBe('urn:ok:error:host-not-allowed');
});
- test('non-ephemeral (project mode): the same rebound Host header still serves', async () => {
- // Proves the gate is ephemeral-scoped — project / desktop asset serving is
- // untouched, so this is not a regression to the existing flow.
+ test('non-ephemeral (project mode): a rebound Host is refused by the content-serve gate', async () => {
+ // Flipped pin (read-posture hardening): project / desktop asset serving
+ // now refuses a rebound Host via the in-middleware content-serve gate —
+ // same predicate as the ephemeral surface gate, host-not-allowed shape.
const { port } = await startAssets(false);
const res = await getWithHost(port, '/secret.png', 'evil.example.com');
- expect(res.status).toBe(200);
+ expect(res.status).toBe(403);
+ expect((JSON.parse(res.body) as { type?: string }).type).toBe('urn:ok:error:host-not-allowed');
});
afterEach(() => {
diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.ts
index 8b6d41a41..f7632263d 100644
--- a/packages/server/src/mcp-mount.ts
+++ b/packages/server/src/mcp-mount.ts
@@ -38,6 +38,7 @@ import {
} from './http/http-app.ts';
import {
buildIngressPolicy,
+ HOST_NOT_ADMITTED_REMEDIATION,
type IngressPolicy,
isHostAdmitted,
isOriginAdmitted,
@@ -239,7 +240,7 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
// The policy's peer + Host gate pair. (With legacy remote armed the
// shared admit gate above already enforced the superset.)
if (!isPeerAdmitted(req.socket.remoteAddress, ingressPolicy)) {
- errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback access required.', {
+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
handler: 'mcp',
});
return;
@@ -247,6 +248,7 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
if (!isHostAdmitted(req.headers.host, ingressPolicy)) {
errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
handler: 'mcp',
+ detail: HOST_NOT_ADMITTED_REMEDIATION,
});
return;
}
@@ -359,18 +361,30 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
// non-admitted caller can't read that user-data dir. Origin is
// intentionally NOT checked: no-cors `<img>` / CSS asset loads omit
// it, and the Host-header check already rejects the rebinding
- // content-exfil vector without that dependency. Project / desktop modes
- // (`ephemeral` falsy) are unchanged — the user chose the served root.
- if (
- ephemeral === true &&
- contentAssetMiddleware !== undefined &&
- (!isPeerAdmitted(req.socket.remoteAddress, ingressPolicy) ||
- !isHostAdmitted(req.headers.host, ingressPolicy))
- ) {
- errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback access required.', {
- handler: 'content-asset',
- });
- return;
+ // content-exfil vector without that dependency. This surface gate
+ // refuses EVERY path in ephemeral mode (even ones that would miss and
+ // fall to the shell); project / desktop modes rely on the in-middleware
+ // content-serve gate (`asset-serve-middleware.ts` policy item 0), which
+ // fires only on actual content-serve attempts so the SPA shell stays
+ // reachable.
+ if (ephemeral === true && contentAssetMiddleware !== undefined) {
+ // Two sequential checks (peer, then Host) so the error TYPE reflects
+ // which one failed — matching the /api pipeline + content-asset gate.
+ // A combined OR emitting a single type mislabels a rebound-Host
+ // refusal as `loopback-required`.
+ if (!isPeerAdmitted(req.socket.remoteAddress, ingressPolicy)) {
+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
+ handler: 'content-asset-gate',
+ });
+ return;
+ }
+ if (!isHostAdmitted(req.headers.host, ingressPolicy)) {
+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
+ handler: 'content-asset-gate',
+ detail: HOST_NOT_ADMITTED_REMEDIATION,
+ });
+ return;
+ }
}
runMiddleware(contentAssetMiddleware, 'content-asset', onMiss);
};