Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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<UiServeconst { resolve } = await import('node:path');const {acquireUiLock,+ buildIngressPolicy,createAssetServeMiddleware,createContentFilter,readServerLock,@@ -280,6 +281,15 @@ export async function startUiServer(opts: StartUiServerOptions): Promise<UiServeinlineExtensions: 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): MdastRothrow 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.tsindex 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.tsindex 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?: StructuralFreshnessChecreturn 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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, MarkdownlintRuleSettingMD013: 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 = adinlineExtensions: 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 createApiEconst 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 createApiEexpect(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.tsindex 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.tsindex 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.tsindex 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): ApiRequestPiif (!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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): MountMcpAndApiHandlif (!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);};