Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(ok): Wave 2 link/graph routes native on Hono (PRD-7813) (#3244)

omar-inkeep86aa3e13bb52
diff --git a/knip.config.ts b/knip.config.ts
index f004e6bc3..13582ee18 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -123,9 +123,7 @@ 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 0327ca7c5..1b84bb634 100644
--- a/packages/app/src/server/hocuspocus-plugin.ts
+++ b/packages/app/src/server/hocuspocus-plugin.ts
@@ -224,8 +224,13 @@ export function hocuspocusPlugin(): Plugin {
}
});
- const { hocuspocus, sessionManager, agentFocusBroadcaster, agentPresenceBroadcaster } =
- currentSrv;
+ const {
+ hocuspocus,
+ nativeApi,
+ sessionManager,
+ agentFocusBroadcaster,
+ agentPresenceBroadcaster,
+ } = currentSrv;
// ACP thread host — the dev twin of boot.ts's construction (the
// documented dual-upgrade-handler drift hazard applies to this whole
@@ -375,6 +380,11 @@ export function hocuspocusPlugin(): Plugin {
}
// Method not GET/HEAD — fall through to 404.
}
+ // Natively-routed /api/* groups (ServerInstance.nativeApi) dispatch
+ // BEFORE the legacy Hocuspocus hook — the dev twin of the Hono
+ // app's above-the-catch-all mount in `mountMcpAndApi`. The shared
+ // pipeline runs either way, so gate behavior is identical.
+ if (await nativeApi.dispatch(req, res)) return;
// biome-ignore lint/suspicious/noExplicitAny: Hocuspocus `hooks()` has no exported payload type for onRequest
await hocuspocus.hooks('onRequest', { request: req, response: res } as any);
// Streaming NDJSON handlers call `writeHead(200)` and return
diff --git a/packages/app/tests/integration/attribution-sweep-coverage.test.ts b/packages/app/tests/integration/attribution-sweep-coverage.test.ts
index be015ba02..624f3679d 100644
--- a/packages/app/tests/integration/attribution-sweep-coverage.test.ts
+++ b/packages/app/tests/integration/attribution-sweep-coverage.test.ts
@@ -16,6 +16,20 @@ import { describe, expect, test } from 'vitest';
const API_EXT_PATH = join(import.meta.dirname, '../../../server/src/api-extension.ts');
const source = readFileSync(API_EXT_PATH, 'utf8');
+/**
+ * Handlers and route records no longer all live in `api-extension.ts`: lifted
+ * groups (`skills-sh-handlers.ts`, and native Wave 2 groups like
+ * `http/link-graph-routes.ts`, which carry their OWN `const routes:` record)
+ * must stay inside the sweep, mirroring `error-envelope-coverage.test.ts` —
+ * otherwise a mutating handler added to a lifted file would ship without a
+ * categorization decision.
+ */
+const HANDLER_SOURCES = [
+ source,
+ ...['skills-sh-handlers.ts', 'http/link-graph-routes.ts'].map((file) =>
+ readFileSync(join(import.meta.dirname, '../../../server/src', file), 'utf8'),
+ ),
+];
const ACTOR_HELPER_PATH = join(
import.meta.dirname,
'../../../server/src/extract-actor-identity.ts',
@@ -416,34 +430,44 @@ const EXEMPT_HANDLERS = new Set([
function extractHandlerBody(handlerName: string): string | null {
// Legacy shape: `async function handle...(`. Migrated shape:
// `const handle... = withValidation(...)`. Both must be supported as the
- // cluster migrations land. Pick whichever appears first in the file.
+ // cluster migrations land. Pick whichever source declares it (a lifted
+ // handler is not in `api-extension.ts`), then whichever shape appears
+ // first in that source.
const fnDecl = `async function ${handlerName}(`;
const constDecl = `const ${handlerName} = withValidation(`;
- const fnIdx = source.indexOf(fnDecl);
- const constIdx = source.indexOf(constDecl);
+ const owner =
+ HANDLER_SOURCES.find((text) => text.includes(fnDecl) || text.includes(constDecl)) ?? source;
+ const fnIdx = owner.indexOf(fnDecl);
+ const constIdx = owner.indexOf(constDecl);
let start = -1;
if (fnIdx !== -1) start = fnIdx;
else if (constIdx !== -1) start = constIdx;
if (start === -1) return null;
- const nextFn = source.indexOf('\n async function handle', start + 1);
- const nextConst = source.indexOf('\n const handle', start + 1);
+ const nextFn = owner.indexOf('\n async function handle', start + 1);
+ const nextConst = owner.indexOf('\n const handle', start + 1);
// Bound the last handler at the route table so the onRequest extension
// body (which uses `errorResponse(...)` for the /api/* Origin gate) is
- // never folded into the handler slice.
- const nextRoutes = source.indexOf('\n const routes:', start + 1);
- const candidates = [nextFn, nextConst, nextRoutes].filter((i) => i !== -1);
+ // never folded into the handler slice. Factory modules end their handler
+ // run at the returned record instead, so bound on that too.
+ const nextRoutes = owner.indexOf('\n const routes:', start + 1);
+ const nextReturn = owner.indexOf('\n return {', start + 1);
+ const candidates = [nextFn, nextConst, nextRoutes, nextReturn].filter((i) => i !== -1);
const next = candidates.length === 0 ? -1 : Math.min(...candidates);
- return source.slice(start, next === -1 ? source.length : next);
+ return owner.slice(start, next === -1 ? owner.length : next);
}
function extractStaticRouteHandlerNames(): string[] {
- const routesStart = source.indexOf('\n const routes:');
- const enableTestRoutes = source.indexOf('\n if (enableTestRoutes)', routesStart);
- const slice =
- routesStart === -1
- ? ''
- : source.slice(routesStart, enableTestRoutes === -1 ? source.length : enableTestRoutes);
- return [...slice.matchAll(/:\s*(handle\w+)/g)].map((m) => m[1]);
+ // Every source's `const routes:` record participates — the legacy dispatch
+ // record in `api-extension.ts` AND each native group's own record.
+ return HANDLER_SOURCES.flatMap((text) => {
+ const routesStart = text.indexOf('\n const routes:');
+ if (routesStart === -1) return [];
+ const enableTestRoutes = text.indexOf('\n if (enableTestRoutes)', routesStart);
+ const nativeTable = text.indexOf('\n const table', routesStart);
+ const bounds = [enableTestRoutes, nativeTable].filter((i) => i !== -1);
+ const slice = text.slice(routesStart, bounds.length === 0 ? text.length : Math.min(...bounds));
+ return [...slice.matchAll(/:\s*(handle\w+)/g)].map((m) => m[1]);
+ });
}
describe('attribution sweep coverage (FR-5, D42)', () => {
diff --git a/packages/app/tests/integration/conflict-gate-coverage.test.ts b/packages/app/tests/integration/conflict-gate-coverage.test.ts
index faca93c35..34a583047 100644
--- a/packages/app/tests/integration/conflict-gate-coverage.test.ts
+++ b/packages/app/tests/integration/conflict-gate-coverage.test.ts
@@ -26,6 +26,19 @@ import { describe, expect, test } from 'vitest';
const API_EXT_PATH = join(import.meta.dirname, '../../../server/src/api-extension.ts');
const source = readFileSync(API_EXT_PATH, 'utf8');
+/**
+ * The conflict-refusal contract applies to any handler that writes user
+ * content, regardless of which file it lives in — lifted route groups
+ * (`skills-sh-handlers.ts`, native Wave 2 groups like
+ * `http/link-graph-routes.ts` with their OWN `const routes:` record) stay
+ * inside the scan, mirroring `error-envelope-coverage.test.ts`.
+ */
+const HANDLER_SOURCES = [
+ source,
+ ...['skills-sh-handlers.ts', 'http/link-graph-routes.ts'].map((file) =>
+ readFileSync(join(import.meta.dirname, '../../../server/src', file), 'utf8'),
+ ),
+];
/**
* The 8 mutating handlers. Each
@@ -321,34 +334,45 @@ const EXEMPT_HANDLERS = new Set([
function extractHandlerBody(handlerName: string): string | null {
// Same legacy vs migrated detection as the attribution-sweep meta-test,
- // plus the `methodRouter({...})` dispatcher shape.
+ // plus the `methodRouter({...})` dispatcher shape. Pick whichever source
+ // declares it (a lifted handler is not in `api-extension.ts`).
const fnDecl = `async function ${handlerName}(`;
const constDecl = `const ${handlerName} = withValidation(`;
const routerDecl = `const ${handlerName} = methodRouter(`;
- const fnIdx = source.indexOf(fnDecl);
- const constIdx = source.indexOf(constDecl);
- const routerIdx = source.indexOf(routerDecl);
+ const owner =
+ HANDLER_SOURCES.find(
+ (text) => text.includes(fnDecl) || text.includes(constDecl) || text.includes(routerDecl),
+ ) ?? source;
+ const fnIdx = owner.indexOf(fnDecl);
+ const constIdx = owner.indexOf(constDecl);
+ const routerIdx = owner.indexOf(routerDecl);
let start = -1;
if (fnIdx !== -1) start = fnIdx;
else if (constIdx !== -1) start = constIdx;
else if (routerIdx !== -1) start = routerIdx;
if (start === -1) return null;
- const nextFn = source.indexOf('\n async function handle', start + 1);
- const nextConst = source.indexOf('\n const handle', start + 1);
- const nextRoutes = source.indexOf('\n const routes:', start + 1);
- const candidates = [nextFn, nextConst, nextRoutes].filter((i) => i !== -1);
+ const nextFn = owner.indexOf('\n async function handle', start + 1);
+ const nextConst = owner.indexOf('\n const handle', start + 1);
+ const nextRoutes = owner.indexOf('\n const routes:', start + 1);
+ // Factory modules end their handler run at the returned record.
+ const nextReturn = owner.indexOf('\n return {', start + 1);
+ const candidates = [nextFn, nextConst, nextRoutes, nextReturn].filter((i) => i !== -1);
const next = candidates.length === 0 ? -1 : Math.min(...candidates);
- return source.slice(start, next === -1 ? source.length : next);
+ return owner.slice(start, next === -1 ? owner.length : next);
}
function extractStaticRouteHandlerNames(): string[] {
- const routesStart = source.indexOf('\n const routes:');
- const enableTestRoutes = source.indexOf('\n if (enableTestRoutes)', routesStart);
- const slice =
- routesStart === -1
- ? ''
- : source.slice(routesStart, enableTestRoutes === -1 ? source.length : enableTestRoutes);
- return [...slice.matchAll(/:\s*(handle\w+)/g)].map((m) => m[1]);
+ // Every source's `const routes:` record participates — the legacy dispatch
+ // record in `api-extension.ts` AND each native group's own record.
+ return HANDLER_SOURCES.flatMap((text) => {
+ const routesStart = text.indexOf('\n const routes:');
+ if (routesStart === -1) return [];
+ const enableTestRoutes = text.indexOf('\n if (enableTestRoutes)', routesStart);
+ const nativeTable = text.indexOf('\n const table', routesStart);
+ const bounds = [enableTestRoutes, nativeTable].filter((i) => i !== -1);
+ const slice = text.slice(routesStart, bounds.length === 0 ? text.length : Math.min(...bounds));
+ return [...slice.matchAll(/:\s*(handle\w+)/g)].map((m) => m[1]);
+ });
}
describe('conflict-gate coverage (FR9)', () => {
diff --git a/packages/app/tests/integration/error-envelope-coverage.test.ts b/packages/app/tests/integration/error-envelope-coverage.test.ts
index 881cc106d..a53da8f4b 100644
--- a/packages/app/tests/integration/error-envelope-coverage.test.ts
+++ b/packages/app/tests/integration/error-envelope-coverage.test.ts
@@ -28,7 +28,11 @@ const SERVER_SRC = join(import.meta.dirname, '../../../server/src');
* `api-extension.ts` would otherwise escape these rules silently rather than
* failing anything.
*/
-const HANDLER_SOURCES = ['api-extension.ts', 'skills-sh-handlers.ts'].map((file) => ({
+const HANDLER_SOURCES = [
+ 'api-extension.ts',
+ 'skills-sh-handlers.ts',
+ 'http/link-graph-routes.ts',
+].map((file) => ({
file,
text: readFileSync(join(SERVER_SRC, file), 'utf8'),
}));
diff --git a/packages/app/tests/integration/test-harness.ts b/packages/app/tests/integration/test-harness.ts
index dca268447..9d4bd5259 100644
--- a/packages/app/tests/integration/test-harness.ts
+++ b/packages/app/tests/integration/test-harness.ts
@@ -335,6 +335,7 @@ export async function createTestServer(options: CreateTestServerOptions = {}): P
const mount = mountMcpAndApi({
httpServer,
hocuspocus: srv.hocuspocus,
+ nativeApi: srv.nativeApi,
mcpHttpHandler,
log: getLogger('test-harness'),
sessionManager: srv.sessionManager,
@@ -1591,6 +1592,7 @@ export async function createRestartableServer(
const mount = mountMcpAndApi({
httpServer,
hocuspocus: srv.hocuspocus,
+ nativeApi: srv.nativeApi,
mcpHttpHandler: undefined,
log: getLogger('restartable-server'),
sessionManager: srv.sessionManager,
diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.ts
index dfd95ef49..d7a845280 100644
--- a/packages/core/src/bridge/bind-frontmatter-doc.ts
+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts
@@ -1,4 +1,3 @@
-
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 8bfdb40cd..005627195 100644
--- a/packages/core/src/bridge/bridge-invariant.ts
+++ b/packages/core/src/bridge/bridge-invariant.ts
@@ -1,4 +1,3 @@
-
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 2a597ec3d..f4cc8a286 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,4 +1,3 @@
-
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 01ef76a9f..8fb428b90 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,4 +1,3 @@
-
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 463e89595..9d9c244b0 100644
--- a/packages/core/src/bridge/growth-detect.ts
+++ b/packages/core/src/bridge/growth-detect.ts
@@ -1,4 +1,3 @@
-
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 0939885bb..c43fdd7e7 100644
--- a/packages/core/src/bridge/intraline-predicate.ts
+++ b/packages/core/src/bridge/intraline-predicate.ts
@@ -1,4 +1,3 @@
-
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 c0dc65705..251560a35 100644
--- a/packages/core/src/bridge/merge-three-way.ts
+++ b/packages/core/src/bridge/merge-three-way.ts
@@ -65,7 +65,6 @@ 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 dcc5b0690..01ac80099 100644
--- a/packages/core/src/bridge/normalize.ts
+++ b/packages/core/src/bridge/normalize.ts
@@ -1,4 +1,3 @@
-
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 0be5203e4..754dc5cc2 100644
--- a/packages/core/src/bridge/pm-structural-equivalence.ts
+++ b/packages/core/src/bridge/pm-structural-equivalence.ts
@@ -32,7 +32,6 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };
const BR_LITERAL_RE = /^<br\s*\/?>$/i;
-
interface DegradeEntry {
readonly label: string;
readonly severity: ToleranceClassSeverity;
@@ -128,7 +127,6 @@ 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(
@@ -250,7 +248,6 @@ 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 dca644141..af20de1e2 100644
--- a/packages/core/src/bridge/subsequence.ts
+++ b/packages/core/src/bridge/subsequence.ts
@@ -1,4 +1,3 @@
-
/** 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 a363dfd54..83d47404a 100644
--- a/packages/core/src/markdown/callout-transformer.ts
+++ b/packages/core/src/markdown/callout-transformer.ts
@@ -1,4 +1,3 @@
-
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 4499dbc92..9807a7e82 100644
--- a/packages/core/src/markdown/code-fence.ts
+++ b/packages/core/src/markdown/code-fence.ts
@@ -1,4 +1,3 @@
-
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 34704165b..7415c474a 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,4 +1,3 @@
-
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 b6299a948..ece5c02a1 100644
--- a/packages/core/src/markdown/dedent-block-jsx-close.ts
+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts
@@ -1,4 +1,3 @@
-
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 acd398aa6..54774764a 100644
--- a/packages/core/src/markdown/details-accordion-promoter.ts
+++ b/packages/core/src/markdown/details-accordion-promoter.ts
@@ -1,4 +1,3 @@
-
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 ba9b56384..43ecdc709 100644
--- a/packages/core/src/markdown/div-align-promoter.ts
+++ b/packages/core/src/markdown/div-align-promoter.ts
@@ -1,4 +1,3 @@
-
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 4513da9bb..6d3f3643e 100644
--- a/packages/core/src/markdown/fence-regions.ts
+++ b/packages/core/src/markdown/fence-regions.ts
@@ -1,4 +1,3 @@
-
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 6931623c7..00f5771ee 100644
--- a/packages/core/src/markdown/fixtures/index.ts
+++ b/packages/core/src/markdown/fixtures/index.ts
@@ -1,4 +1,3 @@
-
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -9,7 +8,6 @@ function fixturePath(...segments: string[]): string {
return resolve(FIXTURES_DIR, ...segments);
}
-
interface GfmExample {
section: string;
markdown: string;
@@ -19,7 +17,6 @@ export function loadGfmExamples(): GfmExample[] {
return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];
}
-
interface MdxCrashEntry {
id: string;
input: string;
@@ -71,7 +68,6 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {
) as LargeEmbedFixture[];
}
-
export function loadPrd6955Before(): string {
return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');
}
@@ -80,7 +76,6 @@ export function loadPrd6955CorruptedTriplicated(): string {
return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');
}
-
export interface NgPinnedCase {
id: string;
name: string;
@@ -97,7 +92,6 @@ 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 daa3ef82b..8b1eb8519 100644
--- a/packages/core/src/markdown/fixtures/perf/generate.ts
+++ b/packages/core/src/markdown/fixtures/perf/generate.ts
@@ -1,4 +1,3 @@
-
import { writeFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -11,7 +10,6 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;
const SEED = 0xf1de1117;
-
function mulberry32(seed: number): () => number {
let a = seed >>> 0;
return () => {
@@ -38,7 +36,6 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {
return items[items.length - 1][0];
}
-
const WORDS = [
'lorem',
'ipsum',
@@ -156,7 +153,6 @@ 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][] = [
@@ -195,7 +191,6 @@ 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 32c055c5b..420dc0fe5 100644
--- a/packages/core/src/markdown/guard-flanking-matrix.ts
+++ b/packages/core/src/markdown/guard-flanking-matrix.ts
@@ -7,7 +7,6 @@ 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 283913255..2653473da 100644
--- a/packages/core/src/markdown/handler-shadow-audit.ts
+++ b/packages/core/src/markdown/handler-shadow-audit.ts
@@ -1,4 +1,3 @@
-
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 5d1000cc4..da0a81d23 100644
--- a/packages/core/src/markdown/highlight-promoter.ts
+++ b/packages/core/src/markdown/highlight-promoter.ts
@@ -1,4 +1,3 @@
-
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 9681c0056..787315157 100644
--- a/packages/core/src/markdown/html-to-mdast.ts
+++ b/packages/core/src/markdown/html-to-mdast.ts
@@ -1,4 +1,3 @@
-
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';
@@ -129,8 +128,7 @@ 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 994eb6917..706fa9afb 100644
--- a/packages/core/src/markdown/image-promoter.ts
+++ b/packages/core/src/markdown/image-promoter.ts
@@ -1,4 +1,3 @@
-
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 69221627d..9075aa7f1 100644
--- a/packages/core/src/markdown/index.ts
+++ b/packages/core/src/markdown/index.ts
@@ -1,4 +1,3 @@
-
import {
type FromProseMirrorOptions,
fromPmMark,
@@ -207,7 +206,6 @@ export class MarkdownManager {
}
}
-
const registry = createRegistry();
function destructureAttrs(
@@ -256,7 +254,6 @@ function destructureAttrs(
return result;
}
-
function hasDirtyDescendant(node: PmNode): boolean {
let found = false;
node.descendants((child) => {
@@ -279,7 +276,6 @@ 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 ?? [];
@@ -348,7 +344,6 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {
return out;
}
-
import {
AUDIO_EXTENSIONS,
FILE_ATTACHMENT_EXTENSIONS,
@@ -601,7 +596,6 @@ function buildMdastToPmHandlers(
}));
}
-
if (m.emphasis) {
handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({
sourceDelimiter: node.data?.sourceDelimiter ?? '*',
@@ -682,7 +676,6 @@ function buildMdastToPmHandlers(
}));
}
-
if (m.link) {
const sourceLiteralMark = m.sourceLiteral;
handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {
@@ -980,7 +973,6 @@ function buildMdastToPmHandlers(
};
}
-
const blockUnknownHandler = (node: {
type: string;
position?: { start: { offset: number }; end: { offset: number } };
@@ -1106,7 +1098,6 @@ 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 b79e9aef7..fa0be9e86 100644
--- a/packages/core/src/markdown/lint/applies-to.ts
+++ b/packages/core/src/markdown/lint/applies-to.ts
@@ -1,4 +1,3 @@
-
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 94b34dee1..312c9c74b 100644
--- a/packages/core/src/markdown/lint/config-files.ts
+++ b/packages/core/src/markdown/lint/config-files.ts
@@ -1,4 +1,3 @@
-
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 e413367ef..0ba33b7d8 100644
--- a/packages/core/src/markdown/lint/config-schemas.ts
+++ b/packages/core/src/markdown/lint/config-schemas.ts
@@ -38,7 +38,6 @@ 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 a51f2ffb0..d48eea5e4 100644
--- a/packages/core/src/markdown/lint/default-config.ts
+++ b/packages/core/src/markdown/lint/default-config.ts
@@ -6,7 +6,6 @@ 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 9c9542661..ef478e268 100644
--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
@@ -1,4 +1,3 @@
-
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 b96d19182..0d4c9a0df 100644
--- a/packages/core/src/markdown/lint/frontmatter-validate.ts
+++ b/packages/core/src/markdown/lint/frontmatter-validate.ts
@@ -1,4 +1,3 @@
-
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 48d260ed6..00d08265a 100644
--- a/packages/core/src/markdown/lint/index.ts
+++ b/packages/core/src/markdown/lint/index.ts
@@ -1,4 +1,3 @@
-
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 be5871ed9..5e832aa19 100644
--- a/packages/core/src/markdown/lint/plugins.ts
+++ b/packages/core/src/markdown/lint/plugins.ts
@@ -1,4 +1,3 @@
-
import { z } from 'zod';
import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';
import {
@@ -14,7 +13,6 @@ 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 833c3a727..3918e657c 100644
--- a/packages/core/src/markdown/lint/types.ts
+++ b/packages/core/src/markdown/lint/types.ts
@@ -1,4 +1,3 @@
-
export const LINT_PLUGIN_IDS = ['markdownlint', 'frontmatter'] as const;
export type LintPluginId = (typeof LINT_PLUGIN_IDS)[number];
@@ -72,7 +71,6 @@ 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 437cc539a..98238656e 100644
--- a/packages/core/src/markdown/lint/validation-counts.ts
+++ b/packages/core/src/markdown/lint/validation-counts.ts
@@ -1,4 +1,3 @@
-
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 bd79424c7..a5b511f25 100644
--- a/packages/core/src/markdown/math-promoter.ts
+++ b/packages/core/src/markdown/math-promoter.ts
@@ -1,4 +1,3 @@
-
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 00fbc0035..ed89371d0 100644
--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts
+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts
@@ -1,4 +1,3 @@
-
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 df788a80d..8ce2b2492 100644
--- a/packages/core/src/markdown/mdast-to-html.ts
+++ b/packages/core/src/markdown/mdast-to-html.ts
@@ -1,4 +1,3 @@
-
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 fa3cfcd86..bfd7e3109 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,4 +1,3 @@
-
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 17ed2b829..1a897fca8 100644
--- a/packages/core/src/markdown/mermaid-promoter.ts
+++ b/packages/core/src/markdown/mermaid-promoter.ts
@@ -1,4 +1,3 @@
-
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 4aa0490c4..d988f4b8b 100644
--- a/packages/core/src/markdown/parse-with-fallback.ts
+++ b/packages/core/src/markdown/parse-with-fallback.ts
@@ -168,7 +168,6 @@ export function parseRecursive(
}
}
-
interface VFilePlace {
offset?: number;
start?: { offset?: number };
@@ -187,7 +186,6 @@ function extractErrorOffset(err: unknown): number | undefined {
return undefined;
}
-
interface Region {
start: number;
end: number;
@@ -211,7 +209,6 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {
return null;
}
-
export interface TagEvent {
kind: 'open' | 'close' | 'self-close';
name: string;
@@ -358,7 +355,6 @@ function findFallbackRegion(src: string, errorOffset: number): Region {
return { start: blockStart, end: blockEnd };
}
-
interface SourceBlock {
src: string;
start: number;
@@ -456,7 +452,6 @@ 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 43d420187..e6ab4fd57 100644
--- a/packages/core/src/markdown/parser-drop-closure.ts
+++ b/packages/core/src/markdown/parser-drop-closure.ts
@@ -1,4 +1,3 @@
-
export type DroppedTokenAdjudication =
| {
kind: 'format-dof-axis';
diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.ts
index 5af2f05f5..449e6f12f 100644
--- a/packages/core/src/markdown/pipeline.ts
+++ b/packages/core/src/markdown/pipeline.ts
@@ -1,4 +1,3 @@
-
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 ccf06e94d..91cdf658f 100644
--- a/packages/core/src/markdown/position-aware-join.ts
+++ b/packages/core/src/markdown/position-aware-join.ts
@@ -1,4 +1,3 @@
-
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 e5b4c9eba..0f399d34c 100644
--- a/packages/core/src/markdown/position-slice.ts
+++ b/packages/core/src/markdown/position-slice.ts
@@ -1,4 +1,3 @@
-
import type { Nodes, Root } from 'mdast';
import { visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
@@ -477,8 +476,7 @@ 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 ca225ce9b..db10fa54b 100644
--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
@@ -1,4 +1,3 @@
-
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 3a2524a9a..34068d103 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
@@ -1,4 +1,3 @@
-
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 2279a0189..93151d43b 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
@@ -1,4 +1,3 @@
-
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 a0f467c42..188f02d83 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
@@ -1,4 +1,3 @@
-
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 4e8542a21..4ba2c3418 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
@@ -1,4 +1,3 @@
-
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 a3c96b24a..1a74b1272 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
@@ -1,4 +1,3 @@
-
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 e95cf43d6..de35e7b79 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
@@ -1,4 +1,3 @@
-
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 ffdb4d5b5..b4be1b2ea 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
@@ -1,4 +1,3 @@
-
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 e2a96d1a7..3c8d88b7c 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
@@ -1,4 +1,3 @@
-
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 0389575ac..cf2c9da8e 100644
--- a/packages/core/src/markdown/resolve-image-url.ts
+++ b/packages/core/src/markdown/resolve-image-url.ts
@@ -1,4 +1,3 @@
-
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 8be632ba4..4d3250d3a 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,4 +1,3 @@
-
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 96304e7a5..0dd54070e 100644
--- a/packages/core/src/markdown/serialize-fidelity.test-helper.ts
+++ b/packages/core/src/markdown/serialize-fidelity.test-helper.ts
@@ -1,4 +1,3 @@
-
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 93798cf83..7cac5b042 100644
--- a/packages/core/src/markdown/serialize-helpers.ts
+++ b/packages/core/src/markdown/serialize-helpers.ts
@@ -1,4 +1,3 @@
-
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 8c08b7a04..b012a5aff 100644
--- a/packages/core/src/markdown/single-dollar-math-promoter.ts
+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts
@@ -1,4 +1,3 @@
-
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 959cc0bd2..3e79f8cb6 100644
--- a/packages/core/src/markdown/to-markdown-handlers.ts
+++ b/packages/core/src/markdown/to-markdown-handlers.ts
@@ -1,4 +1,3 @@
-
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 6e6d73400..0f1b0f27d 100644
--- a/packages/core/src/markdown/underline-promoter.ts
+++ b/packages/core/src/markdown/underline-promoter.ts
@@ -1,4 +1,3 @@
-
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 932d7d2a8..1a082bda7 100644
--- a/packages/core/src/markdown/unknown-mdast-guard.ts
+++ b/packages/core/src/markdown/unknown-mdast-guard.ts
@@ -1,4 +1,3 @@
-
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 ac9f5239b..d578476a7 100644
--- a/packages/core/src/markdown/whitespace-char-ref.ts
+++ b/packages/core/src/markdown/whitespace-char-ref.ts
@@ -1,4 +1,3 @@
-
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 afd9936fe..6dad26200 100644
--- a/packages/core/src/markdown/wiki-link-micromark.ts
+++ b/packages/core/src/markdown/wiki-link-micromark.ts
@@ -17,7 +17,6 @@ declare module 'micromark-util-types' {
}
}
-
const CODE_BANG = 33; // !
const CODE_LBRACKET = 91; // [
const CODE_RBRACKET = 93; // ]
@@ -261,7 +260,6 @@ export function wikiLinkSyntax(): Extension {
};
}
-
function enterWikiLink(this: CompileContext, token: Token) {
this.enter(
{
@@ -387,7 +385,6 @@ export const wikiLinkToMarkdown: {
unsafe: [{ character: '[', inConstruct: ['phrasing'] }],
};
-
const MICROMARK_EXT = wikiLinkSyntax();
export function remarkWikiLink(this: Processor) {
diff --git a/packages/server/src/api-extension.test-helper.ts b/packages/server/src/api-extension.test-helper.ts
index 965dfd85a..a34a6177c 100644
--- a/packages/server/src/api-extension.test-helper.ts
+++ b/packages/server/src/api-extension.test-helper.ts
@@ -1,3 +1,4 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
import type { ApiExtensionOptions } from './api-extension.ts';
import { createApiExtension as createApiExtensionBase } from './api-extension.ts';
import type { BacklinkIndex } from './backlink-index.ts';
@@ -219,11 +220,24 @@ export function createApiExtension(
},
): ReturnType<typeof createApiExtensionBase> {
const { backlinkIndex, tagIndex, derivedDocumentIndex, ...apiOptions } = options;
- return createApiExtensionBase({
+ const extension = createApiExtensionBase({
...apiOptions,
durabilityState: new DocumentDurabilityState(),
derivedDocumentIndex:
derivedDocumentIndex ??
createLegacyDerivedIndexPort(backlinkIndex, tagIndex, options.signalChannel),
});
+ // Mirror the production composition (Hono native mount ABOVE the strangler
+ // catch-all): natively-routed groups dispatch first, everything else flows
+ // through the legacy onRequest hook. Tests that drive `ext.onRequest`
+ // directly keep reaching ported routes through the same shared pipeline.
+ const legacyOnRequest = extension.onRequest?.bind(extension);
+ return {
+ ...extension,
+ async onRequest(payload: { request: IncomingMessage; response: ServerResponse }) {
+ if (await extension.nativeApi.dispatch(payload.request, payload.response)) return;
+ // biome-ignore lint/suspicious/noExplicitAny: Hocuspocus `onRequest` has no exported payload type
+ await legacyOnRequest?.(payload as any);
+ },
+ };
}
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 844015fa6..64af002bb 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -47,13 +47,10 @@ import {
AgentWriteSuccessSchema,
ApiConfigSuccessSchema,
applyPatchToFm,
- BacklinkCountsSuccessSchema,
- BacklinksSuccessSchema,
type BatchEntryError,
BranchInfoResponseSchema,
CheckoutRequestSchema,
CheckoutResponseSchema,
- CLIENT_VERSION_HEADER,
ClientLogsRequestSchema,
ClientLogsSuccessSchema,
CONFIG_DOC_NAME_OKIGNORE,
@@ -72,7 +69,6 @@ import {
DEFAULT_EMBEDDINGS_MODEL,
DEFAULT_LINKS_VALIDATION,
DEFAULT_LINTER_CONFIG,
- DeadLinksSuccessSchema,
DeletePathRequestSchema,
DeletePathSuccessSchema,
type DiskEditReconciledWarning,
@@ -91,7 +87,6 @@ import {
FolderConfigGetSuccessSchema,
FolderConfigPutRequestSchema,
FolderConfigPutSuccessSchema,
- ForwardLinksSuccessSchema,
FrontmatterPatchRequestSchema,
FrontmatterPatchSuccessSchema,
FrontmatterSchemasListSuccessSchema,
@@ -114,7 +109,6 @@ import {
LEGACY_SKILL_STORE_ROOT,
LINKABLE_ASSET_EXTENSIONS,
type LifecycleStatus,
- LinkGraphSuccessSchema,
LinkPreviewRequestSchema,
LinkPreviewResponseSchema,
type LinksValidationSetting,
@@ -237,7 +231,6 @@ import {
SkillTargetsPutSuccessSchema,
SkillUninstallRequestSchema,
SkillUninstallSuccessSchema,
- SuggestLinksSuccessSchema,
SYSTEM_DOC_NAME,
SyncConflictContentSuccessSchema,
SyncConflictsSuccessSchema,
@@ -249,8 +242,6 @@ import {
scanHeadingLine,
skillLiveDocName,
stripFrontmatter,
- TagsForNameSuccessSchema,
- TagsListSuccessSchema,
TemplateDeleteSuccessSchema,
TemplateGetSuccessSchema,
TemplateImportRequestSchema,
@@ -338,7 +329,6 @@ import {
snapshotBlocks,
} from './agent-sessions.ts';
import { type NormalizedSummary, normalizeSummary } from './agent-write-summary.ts';
-import { isAllowedApiOrigin } from './api-origin.ts';
import { collectReferencedAssets } from './asset-references.ts';
import { collabUrlFromRequestHeaders } from './collab-bootstrap-url.ts';
import { createCommentApi } from './comments/comment-api.ts';
@@ -379,7 +369,7 @@ import {
toContentDivergenceWarning,
} from './content-divergence-gate.ts';
import { recordContributor } from './contributor-tracker.ts';
-import { deriveDetection, embedProbeRing, recordEmbedProbe } from './embed-probe.ts';
+import { deriveDetection, embedProbeRing } from './embed-probe.ts';
import {
FileEmbeddingsBackend,
probeEmbeddingEndpoint,
@@ -525,15 +515,6 @@ function bundleSelfIdentifiesAsPack(dir: string): boolean {
export { extractPageTitle } from './page-identity.ts';
import type { SkillHostId } from '@inkeep/open-knowledge-core/skills-catalog';
-import { context, propagation, SpanKind, SpanStatusCode } from '@opentelemetry/api';
-import {
- ATTR_HTTP_REQUEST_METHOD,
- ATTR_HTTP_RESPONSE_STATUS_CODE,
- ATTR_HTTP_ROUTE,
- ATTR_URL_PATH,
- ATTR_URL_SCHEME,
- ATTR_USER_AGENT_ORIGINAL,
-} from '@opentelemetry/semantic-conventions';
import simpleGit from 'simple-git';
import { parseAgentBodyFields, resolveAgentType, validateAgentId } from './agent-id.ts';
import {
@@ -566,7 +547,6 @@ import { safeContentPath } from './content-path.ts';
import {
type DerivedDocumentIndexApiPort,
type DerivedDocumentIndexMutation,
- type DerivedGraphNode,
isDerivedDocumentIndexClosedError,
isDerivedOrphanMode,
} from './derived-document-index.ts';
@@ -620,6 +600,7 @@ import {
import { CHECKOUT_HANDLER_TAG, runCheckoutFlow } from './git-checkout.ts';
import { withParentLock } from './git-handle.ts';
import { writeGitIdentity } from './git-identity.ts';
+import { type ApiRouteTable, createApiRequestPipeline } from './http/api-pipeline.ts';
import { catchErrors } from './http/catch-errors.ts';
import {
createStreamingErrorWriter,
@@ -627,13 +608,10 @@ import {
type HttpErrorStatus,
} from './http/error-response.ts';
import { errnoCode, parseQuery } from './http/handler-utils.ts';
+import { assertSingleRouterOwnership, type NativeApiHandle } from './http/http-app.ts';
+import { createLinkGraphRoutes } from './http/link-graph-routes.ts';
import { methodRouter } from './http/method-router.ts';
-import {
- getRequestId,
- REQUEST_ID_HEADER,
- rememberRequestId,
- resolveRequestId,
-} from './http/request-id.ts';
+import { getRequestId } from './http/request-id.ts';
import { validateBody, withValidation } from './http/request-validation.ts';
import { successResponse } from './http/success-response.ts';
import {
@@ -749,28 +727,14 @@ import { restoreSkillVersion } from './skill-restore.ts';
import { mutateSkillsLock, readSkillsLockFile } from './skills-lock-store.ts';
import { createSkillsShHandlers } from './skills-sh-handlers.ts';
import { reportSkillInstall } from './skills-sh-install-report.ts';
-import { SuggestLinksTargetNotFoundError, suggestLinks } from './suggest-links.ts';
import type { SyncEngine } from './sync-engine.ts';
-import { getMeter, getTracer, withSpan, withSpanSync } from './telemetry.ts';
+import { getMeter, withSpan, withSpanSync } from './telemetry.ts';
import { getDocumentHistory, getFolderTimeline } from './timeline-query.ts';
import { recordTimelineCoalesced } from './timeline-telemetry.ts';
-// Cache the HTTP duration histogram at module scope — lazy-init at first use
-// so the meter is a real meter (post-`initTelemetry`), not the pre-init no-op.
-// Recreating the histogram every request allocates + registers a fresh
-// instrument on every hit.
-let _httpDurationHist: ReturnType<ReturnType<typeof getMeter>['createHistogram']> | null = null;
-
-function httpDurationHist(): ReturnType<ReturnType<typeof getMeter>['createHistogram']> {
- _httpDurationHist ||= getMeter().createHistogram('http.server.request.duration', {
- description: 'HTTP server request duration in seconds',
- unit: 's',
- });
- return _httpDurationHist;
-}
-
// Lazy-init so the counter registers against a real meter post-initTelemetry
-// (not the pre-init no-op). Matches the httpDurationHist pattern.
+// (not the pre-init no-op). Matches the httpDurationHist pattern in
+// http/api-pipeline.ts.
let _hintEmittedCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null = null;
function hintEmittedCounter(): ReturnType<ReturnType<typeof getMeter>['createCounter']> {
_hintEmittedCounter ||= getMeter().createCounter('ok.preview_attach.hint_emitted', {
@@ -2829,7 +2793,9 @@ export interface CommentDocHooks {
deleted: (docName: string) => void;
}
-export function createApiExtension(options: ApiExtensionOptions): Extension {
+export function createApiExtension(
+ options: ApiExtensionOptions,
+): Extension & { nativeApi: NativeApiHandle } {
const { durabilityState, remotePublicHost } = options;
// Every local-op call site in this factory inherits the remote-origin
// widening through this shadow — one choke point, zero per-site churn.
@@ -7140,57 +7106,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
{ handler: 'document-list', method: 'GET', skipBodyParse: true },
);
- const handleBacklinks = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- if (!derivedDocumentIndex) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:backlink-index-not-configured',
- 'Backlink index is not configured.',
- { handler: 'backlinks' },
- );
- return;
- }
- try {
- const url = new URL(req.url ?? '', 'http://localhost');
- const docName = url.searchParams.get('docName');
- if (!docName) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {
- handler: 'backlinks',
- });
- return;
- }
- if (!isSafeDocName(docName)) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
- handler: 'backlinks',
- });
- return;
- }
- const backlinks = (await derivedDocumentIndex.getBacklinks(docName)).map((entry) => ({
- source: entry.source,
- anchor: entry.anchor,
- title: readPageTitleForDocName(entry.source),
- snippet: entry.snippet,
- }));
- successResponse(
- res,
- 200,
- BacklinksSuccessSchema,
- { docName, backlinks },
- { handler: 'backlinks' },
- );
- } catch (e) {
- respondToDerivedIndexQueryFailure(res, e, {
- handler: 'backlinks',
- failureTitle: 'Failed to read backlinks.',
- });
- }
- },
- { handler: 'backlinks', method: 'GET', skipBodyParse: true },
- );
-
/**
* Read-only cross-harness installed-skill enumeration. `GET /api/skills/installed`
* returns `{ skills, packs }` — every skill OK can see across all harness
@@ -7244,57 +7159,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
{ handler: 'skills-installed', method: 'GET', skipBodyParse: true },
);
- /**
- * Bulk backlink-count lookup. `GET /api/backlink-counts?docNames=a,b,c`
- * returns `{ counts: { a: 3, b: 0, c: 2 } }`. Serves listing UIs
- * (exec ls/grep/find slim enrichment) that need connection density per file
- * without N-amplifying the single-doc `/api/backlinks` endpoint.
- * docNames failing `isSafeDocName` are silently dropped from `counts`.
- */
- const handleBacklinkCounts = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- if (!derivedDocumentIndex) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:backlink-index-not-configured',
- 'Backlink index is not configured.',
- { handler: 'backlink-counts' },
- );
- return;
- }
- try {
- const url = new URL(req.url ?? '', 'http://localhost');
- const raw = url.searchParams.get('docNames');
- if (!raw) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docNames parameter.', {
- handler: 'backlink-counts',
- });
- return;
- }
- const docNames = raw
- .split(',')
- .map((docName) => docName.trim())
- .filter((docName) => docName && isSafeDocName(docName));
- const counts = await derivedDocumentIndex.getBacklinkCounts(docNames);
- successResponse(
- res,
- 200,
- BacklinkCountsSuccessSchema,
- { counts },
- { handler: 'backlink-counts' },
- );
- } catch (e) {
- respondToDerivedIndexQueryFailure(res, e, {
- handler: 'backlink-counts',
- failureTitle: 'Failed to read backlink counts.',
- });
- }
- },
- { handler: 'backlink-counts', method: 'GET', skipBodyParse: true },
- );
-
/**
* Bulk unresolved-comment-count lookup, the read-side counterpart to
* `/api/backlink-counts`. `GET /api/comment-counts?docNames=a,b,c` returns
@@ -7364,169 +7228,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
{ handler: 'comment-counts', method: 'GET', skipBodyParse: true },
);
- const handleForwardLinks = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- if (!derivedDocumentIndex) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:backlink-index-not-configured',
- 'Backlink index is not configured.',
- { handler: 'forward-links' },
- );
- return;
- }
- try {
- const url = new URL(req.url ?? '', 'http://localhost');
- const docName = url.searchParams.get('docName');
- if (!docName) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {
- handler: 'forward-links',
- });
- return;
- }
- if (!isSafeDocName(docName)) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
- handler: 'forward-links',
- });
- return;
- }
- const admitted = await collectAdmittedDocNames();
- successResponse(
- res,
- 200,
- ForwardLinksSuccessSchema,
- {
- docName,
- forwardLinks: (await derivedDocumentIndex.getForwardLinkEntries(docName)).map(
- (entry) =>
- entry.kind === 'doc'
- ? {
- kind: 'doc' as const,
- docName: entry.target,
- anchor: entry.anchor,
- title: readPageTitleForLinkedDocName(entry.target, admitted),
- snippet: entry.snippet,
- }
- : {
- kind: 'external' as const,
- url: entry.url,
- title: entry.label ?? entry.url,
- snippet: entry.snippet,
- },
- ),
- },
- { handler: 'forward-links' },
- );
- } catch (e) {
- respondToDerivedIndexQueryFailure(res, e, {
- handler: 'forward-links',
- failureTitle: 'Failed to read forward links.',
- });
- }
- },
- { handler: 'forward-links', method: 'GET', skipBodyParse: true },
- );
-
- const handleLinkGraph = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- if (!derivedDocumentIndex) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:backlink-index-not-configured',
- 'Backlink index is not configured.',
- { handler: 'link-graph' },
- );
- return;
- }
- try {
- const url = new URL(req.url ?? '', 'http://localhost');
- const docName = url.searchParams.get('docName');
- if (docName && !isSafeDocName(docName)) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
- handler: 'link-graph',
- });
- return;
- }
-
- const rawDegrees = url.searchParams.get('degrees');
- if (rawDegrees && !docName) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'docName is required when degrees is provided.',
- { handler: 'link-graph' },
- );
- return;
- }
-
- let nodes: DerivedGraphNode[];
- let links: Array<{ source: string; target: string }>;
-
- if (rawDegrees && docName) {
- const degrees = Number.parseInt(rawDegrees, 10);
- if (!Number.isFinite(degrees) || degrees < 0) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'degrees must be a non-negative integer.',
- { handler: 'link-graph' },
- );
- return;
- }
-
- ({ nodes, links } = await derivedDocumentIndex.getLinkGraphNeighborhood(
- docName,
- degrees,
- ));
- } else {
- ({ nodes, links } = await derivedDocumentIndex.getLinkGraph());
- }
-
- const admitted = await collectAdmittedDocNames();
- const enrichedNodes = nodes.map((node) => {
- if (node.kind === 'doc') {
- const meta = readFrontmatterMetadataForLinkedDocName(node.docName, admitted);
- return {
- id: node.id,
- kind: 'doc' as const,
- docName: node.docName,
- anchor: node.anchor ?? null,
- label: readPageTitleForLinkedDocName(node.docName, admitted),
- cluster: meta.cluster ?? null,
- category: meta.category ?? null,
- tags: meta.tags ?? null,
- };
- }
- return {
- id: node.id,
- kind: 'external' as const,
- url: node.url,
- label: node.label ?? node.url,
- };
- });
- successResponse(
- res,
- 200,
- LinkGraphSuccessSchema,
- { nodes: enrichedNodes, links },
- { handler: 'link-graph' },
- );
- } catch (e) {
- respondToDerivedIndexQueryFailure(res, e, {
- handler: 'link-graph',
- failureTitle: 'Failed to read link graph.',
- });
- }
- },
- { handler: 'link-graph', method: 'GET', skipBodyParse: true },
- );
-
const handleOrphans = withValidation(
EmptyRequestSchema,
async (req, res) => {
@@ -7606,63 +7307,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
{ handler: 'hubs', method: 'GET', skipBodyParse: true },
);
- const handleDeadLinks = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- if (!derivedDocumentIndex) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:backlink-index-not-configured',
- 'Backlink index is not configured.',
- { handler: 'dead-links' },
- );
- return;
- }
- try {
- const url = new URL(req.url ?? '', 'http://localhost');
- const sourceDocNames = url.searchParams.getAll('sourceDocName');
- if (sourceDocNames.some((docName) => docName.length === 0 || !isSafeDocName(docName))) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid sourceDocName.', {
- handler: 'dead-links',
- });
- return;
- }
-
- const sourceDocNameFilter = sourceDocNames.length
- ? [...new Set(sourceDocNames.map((docName) => resolveAlias(docName)))]
- : undefined;
- const deadLinks = await derivedDocumentIndex.getDeadLinks(
- await collectAdmittedDocNames(),
- sourceDocNameFilter,
- );
-
- successResponse(
- res,
- 200,
- DeadLinksSuccessSchema,
- {
- deadLinks: deadLinks.map((entry) => ({
- target: entry.target,
- sources: entry.sources.map((sourceEntry) => ({
- source: sourceEntry.source,
- title: readPageTitleForDocName(sourceEntry.source),
- snippet: sourceEntry.snippet,
- })),
- })),
- },
- { handler: 'dead-links' },
- );
- } catch (e) {
- respondToDerivedIndexQueryFailure(res, e, {
- handler: 'dead-links',
- failureTitle: 'Failed to read dead links.',
- });
- }
- },
- { handler: 'dead-links', method: 'GET', skipBodyParse: true },
- );
-
const handleAgentPatch = withValidation(
AgentPatchRequestSchema,
async (_req, res, body) => {
@@ -11320,58 +10964,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
{ handler: 'pages', method: 'GET', skipBodyParse: true },
);
- const handleSuggestLinks = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- try {
- const url = new URL(req.url ?? '', 'http://localhost');
- const docName = url.searchParams.get('docName');
- if (!docName) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {
- handler: 'suggest-links',
- });
- return;
- }
- if (!isSafeDocName(docName)) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
- handler: 'suggest-links',
- });
- return;
- }
- if (isSystemDoc(docName) || isConfigDoc(docName)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- `'${docName}' is a reserved document name.`,
- { handler: 'suggest-links' },
- );
- return;
- }
-
- const result = await suggestLinks({
- hocuspocus,
- fileIndex: getFileIndex(),
- docName,
- });
- successResponse(res, 200, SuggestLinksSuccessSchema, result, { handler: 'suggest-links' });
- } catch (error) {
- if (error instanceof SuggestLinksTargetNotFoundError) {
- errorResponse(res, 404, 'urn:ok:error:doc-not-found', 'Page not found.', {
- handler: 'suggest-links',
- cause: error,
- });
- return;
- }
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to suggest links.', {
- handler: 'suggest-links',
- cause: error,
- });
- }
- },
- { handler: 'suggest-links', method: 'GET', skipBodyParse: true },
- );
-
async function handleUploadAsset(req: IncomingMessage, res: ServerResponse): Promise<void> {
if (req.method !== 'POST') {
errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
@@ -13853,95 +13445,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
}
}
- const handleTagsList = withValidation(
- EmptyRequestSchema,
- async (_req, res) => {
- if (!derivedDocumentIndex) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:tag-index-not-configured',
- 'Tag index not configured.',
- { handler: 'tags-list' },
- );
- return;
- }
- try {
- const tags = await derivedDocumentIndex.getAllTags();
- successResponse(res, 200, TagsListSuccessSchema, { tags }, { handler: 'tags-list' });
- } catch (e) {
- respondToDerivedIndexQueryFailure(res, e, {
- handler: 'tags-list',
- failureTitle: 'Failed to read tags.',
- });
- }
- },
- { handler: 'tags-list', method: 'GET', skipBodyParse: true },
- );
-
- async function handleTagsForName(
- req: IncomingMessage,
- res: ServerResponse,
- rawName: string,
- ): Promise<void> {
- if (req.method !== 'GET') {
- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
- handler: 'tags-for-name',
- extraHeaders: { Allow: 'GET' },
- });
- return;
- }
- if (!derivedDocumentIndex) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:tag-index-not-configured',
- 'Tag index not configured.',
- { handler: 'tags-for-name' },
- );
- return;
- }
- let name: string;
- try {
- name = decodeURIComponent(rawName);
- } catch {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid tag name encoding.', {
- handler: 'tags-for-name',
- });
- return;
- }
- if (!name) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing tag name.', {
- handler: 'tags-for-name',
- });
- return;
- }
- try {
- const docs = (await derivedDocumentIndex.getDocsForTagWithMatches(name)).map(
- ({ docName, matchingTags }) => ({
- docName,
- title: readPageTitleForDocName(docName),
- matchingTags,
- snippet: null,
- }),
- );
- successResponse(
- res,
- 200,
- TagsForNameSuccessSchema,
- { name, docs },
- {
- handler: 'tags-for-name',
- },
- );
- } catch (e) {
- respondToDerivedIndexQueryFailure(res, e, {
- handler: 'tags-for-name',
- failureTitle: 'Failed to read tag membership.',
- });
- }
- }
-
function validateFolderRel(
raw: string,
res: ServerResponse,
@@ -22892,16 +22395,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
'/api/asset-text': handleAssetText,
'/api/document': handleDocumentRead,
'/api/documents': handleDocumentList,
- '/api/backlinks': handleBacklinks,
- '/api/backlink-counts': handleBacklinkCounts,
'/api/comment-counts': handleCommentCounts,
'/api/link-preview': handleLinkPreview,
- '/api/forward-links': handleForwardLinks,
- '/api/link-graph': handleLinkGraph,
- '/api/dead-links': handleDeadLinks,
'/api/orphans': handleOrphans,
'/api/hubs': handleHubs,
- '/api/tags': handleTagsList,
'/api/pages': handlePages,
'/api/folder-config': handleFolderConfig,
'/api/template': handleTemplate,
@@ -22940,7 +22437,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
'/api/lint/audit': handleLintAudit,
'/api/lint/fix': handleLintFix,
'/api/audit': handleAudit,
- '/api/suggest-links': handleSuggestLinks,
'/api/page-headings': handlePageHeadings,
'/api/create-page': handleCreatePage,
'/api/create-folder': handleCreateFolder,
@@ -23081,353 +22577,79 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
// by default.
const STATE_MUTATING_PREFIXES: ReadonlyArray<string> = ['/api/local-op/'];
- return {
- priority: 100, // Higher priority — API routes run before static file serving
- async onRequest({ request, response }: { request: IncomingMessage; response: ServerResponse }) {
- const url = request.url?.split('?')[0];
- if (!url) return;
-
- // Per-request client-context observation for embed-detection spikes.
- // Pushed into a bounded in-process ring buffer drained by
- // /api/__embed-detect. Assumes loopback-only deployment — the consumer
- // endpoint enforces this. Multi-valued headers (rare) collapse to the
- // joined string Node provides by default for the headers we capture.
- const headerString = (name: string): string | undefined => {
- const value = request.headers[name];
- if (value === undefined) return undefined;
- return Array.isArray(value) ? value.join(', ') : value;
- };
- recordEmbedProbe({
- ts: Date.now(),
- url,
- method: request.method ?? '',
- ua: headerString('user-agent'),
- origin: headerString('origin'),
- referer: headerString('referer'),
- host: headerString('host'),
- remote: request.socket?.remoteAddress,
- secChUa: headerString('sec-ch-ua'),
- secChUaMobile: headerString('sec-ch-ua-mobile'),
- secChUaPlatform: headerString('sec-ch-ua-platform'),
- secFetchSite: headerString('sec-fetch-site'),
- secFetchDest: headerString('sec-fetch-dest'),
- secFetchMode: headerString('sec-fetch-mode'),
- secFetchUser: headerString('sec-fetch-user'),
- });
-
- const method = request.method ?? 'GET';
- // Normalize route for low-cardinality labels (metric labels, span
- // attributes, and the access log below). `:id` placeholders replace
- // dynamic segments; anything else collapses to the URL prefix.
- let routeTemplate = url;
- if (url.startsWith('/api/history/')) routeTemplate = '/api/history/:sha';
- else if (url.startsWith('/api/tags/')) routeTemplate = '/api/tags/:name';
- else if (!routes[url]) routeTemplate = '/api/*';
-
- // Request identity + access log for the /api/* surface. Slots BEFORE the
- // origin/loopback/host gates (without touching their order) so even
- // gate-rejected responses carry the `x-request-id` echo and produce an
- // access-log line. The `typeof` guards mirror the CORS block below —
- // unit-test doubles stub only `writeHead` + `end`.
- const requestId = url.startsWith('/api/') ? resolveRequestId(request) : undefined;
- if (requestId !== undefined) {
- rememberRequestId(request, requestId);
- if (typeof response.setHeader === 'function') {
- response.setHeader(REQUEST_ID_HEADER, requestId);
- }
- if (typeof response.once === 'function') {
- const accessStarted = Date.now();
- let accessLogged = false;
- // One line per request on whichever of finish/close fires first:
- // 'finish' is the fully-flushed response (including long-lived
- // NDJSON streams, logged at stream end); 'close' catches aborted
- // sockets (client disconnect, timeout destroy) that never finish.
- // Route TEMPLATE, never the raw path — cardinality discipline for
- // log aggregators matches the metric-label STOP rule. Byte counts
- // are omitted: Node exposes no cheap per-response counter under
- // chunked encoding (socket.bytesWritten is per-connection).
- const emitAccessLog = () => {
- if (accessLogged) return;
- accessLogged = true;
- log.info(
- {
- event: 'api.access',
- requestId,
- method,
- route: routeTemplate,
- status: response.statusCode,
- durationMs: Date.now() - accessStarted,
- ...(response.writableFinished ? {} : { aborted: true }),
- },
- `${method} ${routeTemplate} ${response.statusCode}`,
- );
- };
- response.once('finish', emitAccessLog);
- response.once('close', emitAccessLog);
- }
- }
-
- // Origin-allowlist CORS for /api/*. Only loopback origins are accepted:
- // - No Origin header (same-origin browser tab, curl, CLI): passes through.
- // - Origin "null" (Electron packaged renderer, file:// per Fetch spec §4.3): allowed.
- // - http(s)://localhost[:port] / 127.x.x.x[:port] / [::1][:port]: allowed.
- // - Any other Origin: 403 — closes the CSRF door on unauthenticated mutating
- // routes (/api/agent-write-md, /api/rollback, /api/manage/delete, etc.)
- // without breaking the Electron renderer or local Vite dev servers.
- //
- // When an allowed Origin is present, it is reflected verbatim in ACAO (not
- // `*`) so the browser's preflight check passes while non-loopback origins are
- // still refused by the gate above. `Vary: Origin` prevents cache poisoning.
- //
- // Setting via `setHeader` (not `writeHead`) so handler responses that call
- // `writeHead(status, { ... })` inherit these headers. The typeof guard handles
- // unit tests that stub only `writeHead` + `end`.
- if (url.startsWith('/api/')) {
- const origin = request.headers.origin;
- if (origin !== undefined && !isAllowedApiOrigin(origin, remotePublicHost)) {
- // RFC 9457 problem+json. Tag the handler as `api-origin-gate` so
- // the `ok.api.error.count` counter distinguishes onRequest-level
- // CSRF rejections from per-handler emits. The cross-origin browser
- // can't read the body anyway (CORS strips it) but consistent wire
- // shape lets server-to-server callers + tests parse uniformly.
- errorResponse(response, 403, 'urn:ok:error:invalid-origin', 'Origin not allowed.', {
- handler: 'api-origin-gate',
- });
- return;
- }
- if (typeof response.setHeader === 'function') {
- if (origin !== undefined) {
- response.setHeader('Access-Control-Allow-Origin', origin);
- response.setHeader('Vary', 'Origin');
- }
- response.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
- // Content-Type/Authorization: standard request headers. traceparent/
- // tracestate/baggage: OTel W3C trace-context propagation from the
- // browser SDK. x-ok-client-*: the client→version metadata the renderer
- // stamps on every /api/* request (clientVersionHeaders) — omitting
- // these fails the preflight for the cross-origin renderer (dev Vite
- // origin / file:// packaged) before the real request fires.
- response.setHeader(
- 'Access-Control-Allow-Headers',
- `Content-Type, Authorization, traceparent, tracestate, baggage, ${REQUEST_ID_HEADER}, ${CLIENT_VERSION_HEADER.protocol}, ${CLIENT_VERSION_HEADER.runtime}, ${CLIENT_VERSION_HEADER.kind}`,
- );
- // Let cross-origin renderer JS read the correlation ID echo — CORS
- // hides non-safelisted response headers by default.
- response.setHeader('Access-Control-Expose-Headers', REQUEST_ID_HEADER);
- }
- // OPTIONS preflight — short-circuit with 204 + the headers above.
- if (request.method === 'OPTIONS') {
- response.writeHead(204);
- response.end();
- return;
- }
+ // The legacy route table's view for the shared /api/* admission pipeline
+ // (`http/api-pipeline.ts` — the same pipeline the native Hono routes run).
+ // `resolve` never declines an /api/* URL: unmatched paths resolve to the
+ // bounded `/api/*` template with no dispatch so the pipeline's explicit
+ // RFC 9457 404 owns the response and the dispatch surface stays closed.
+ const apiRouteTable: ApiRouteTable = {
+ resolve(url) {
+ const handler = routes[url];
+ if (handler) {
+ return { template: url, dispatch: (req, res) => handler(req, res) };
}
-
- // DNS-rebinding defense for state-mutating endpoints. The
- // `isLoopbackAddress` TCP-peer check and `isAllowedWorkspaceHostHeader`
- // Host-header check together block the standard rebinding pattern
- // (attacker-owned hostname whose DNS resolves to 127.0.0.1 after an
- // initial attacker-serves-JS response — the TCP peer is loopback,
- // but the Host header names the attacker domain). The same mitigation
- // already gates `/api/workspace`; without it, a rebinding page could
- // POST /api/upload + /api/agent-write, mutating the local vault.
- //
- // Test-harness note: Node's production socket always has
- // `remoteAddress` set by the kernel; the only path that reaches
- // this check without a socket is a mocked `IncomingMessage` built
- // from `Readable.from(...)`. Those mocks bypass the HTTP listener
- // entirely and can't be reached by a real remote attacker, so a
- // missing socket is treated as test-context and skips the check.
- // The Host-header gate still fires (tests set `host: 'localhost'`),
- // so the protection remains meaningful for any production path.
- if (MUTATING_ROUTES.has(url) || STATE_MUTATING_PREFIXES.some((p) => url.startsWith(p))) {
- const peerAddress = request.socket?.remoteAddress;
- if (peerAddress !== undefined && !isLoopbackAddress(peerAddress)) {
- errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
- handler: 'api-mutating-gate',
- });
- return;
- }
- if (!isAllowedWorkspaceHostHeader(request.headers.host)) {
- errorResponse(
- response,
- 403,
- 'urn:ok:error:host-not-allowed',
- 'Host header not allowed.',
- { handler: 'api-mutating-gate' },
- );
- return;
- }
- }
-
- // 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/')) {
- const peerAddress = request.socket?.remoteAddress;
- if (peerAddress !== undefined && !isLoopbackAddress(peerAddress)) {
- errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
- handler: 'api-ephemeral-gate',
- });
- return;
- }
- if (!isAllowedWorkspaceHostHeader(request.headers.host)) {
- errorResponse(
- response,
- 403,
- 'urn:ok:error:host-not-allowed',
- 'Host header not allowed.',
- {
- handler: 'api-ephemeral-gate',
- },
- );
- return;
- }
+ if (url.startsWith('/api/history/')) {
+ const encodedSha = url.slice('/api/history/'.length);
+ return {
+ template: '/api/history/:sha',
+ // Decode inside dispatch so a malformed encoding surfaces as the
+ // dispatch span's typed 500, not a resolve-time throw.
+ dispatch: encodedSha
+ ? async (req, res) => {
+ await handleHistoryVersion(req, res, decodeURIComponent(encodedSha));
+ }
+ : undefined,
+ };
}
+ return { template: '/api/*' };
+ },
+ isMutating: (url) =>
+ MUTATING_ROUTES.has(url) || STATE_MUTATING_PREFIXES.some((p) => url.startsWith(p)),
+ };
- // Only /api/* gets a server span. Non-API routes (static file serving,
- // Hocuspocus's own paths) fall through silently. (Route dispatch
- // happens inside the OTel active-span block below.)
- if (!url.startsWith('/api/')) return;
-
- // Extract incoming trace context (W3C traceparent header) so this server
- // span attaches as a child of the browser-initiated trace.
- const extractedCtx = propagation.extract(context.active(), request.headers);
-
- const tracer = getTracer();
- const started = Date.now();
- await context.with(extractedCtx, () =>
- tracer.startActiveSpan(
- `HTTP ${method} ${routeTemplate}`,
- {
- kind: SpanKind.SERVER,
- attributes: {
- [ATTR_HTTP_REQUEST_METHOD]: method,
- [ATTR_HTTP_ROUTE]: routeTemplate,
- [ATTR_URL_PATH]: url,
- [ATTR_URL_SCHEME]: 'http',
- [ATTR_USER_AGENT_ORIGINAL]: request.headers['user-agent'] ?? '',
- // Correlation ID (UUID or client-supplied bounded token) — a
- // sanctioned span attribute like `ok.error.instance`; the
- // cardinality STOP rule governs metric labels, which stay
- // request-id-free.
- 'ok.request.id': requestId,
- },
- },
- async (span) => {
- try {
- // Static routes
- const handler = routes[url];
- let dispatched = false;
- if (handler) {
- dispatched = true;
- await handler(request, response);
- } else if (url.startsWith('/api/history/')) {
- const sha = decodeURIComponent(url.slice('/api/history/'.length));
- if (sha) {
- dispatched = true;
- await handleHistoryVersion(request, response, sha);
- }
- } else if (url.startsWith('/api/tags/')) {
- const rawName = url.slice('/api/tags/'.length);
- if (rawName) {
- dispatched = true;
- await handleTagsForName(request, response, rawName);
- }
- }
+ const runApiPipeline = createApiRequestPipeline({
+ log,
+ remotePublicHost,
+ ephemeral,
+ table: apiRouteTable,
+ });
- // Defense-in-depth: unmatched `/api/*` routes (typos, removed
- // endpoints, empty `/api/rescue/` / `/api/history/` segments)
- // would otherwise fall through with no response body, leaving
- // Hocuspocus's `onRequest` machinery to either pass through to
- // static-file middleware or hang. Emit an explicit RFC 9457 404
- // so the dispatch surface is fully closed. Dispatch flag is
- // robust against test-mock `ServerResponse` shapes that don't
- // simulate `headersSent` (vs checking `response.headersSent`
- // directly, which would misfire on mocks after a handler
- // successfully wrote 200).
- if (!dispatched) {
- // `detail` echoes the actual requested URL (no information
- // leak — the client sent it). `routeTemplate` is bounded
- // to `/api/*` for unmatched routes and used only for
- // histogram labels / span attributes upstream — keeping
- // the two concerns separate so the wire-detail stays
- // actionable for debuggers without coupling to the
- // cardinality-bounded telemetry surface.
- errorResponse(response, 404, 'urn:ok:error:not-found', 'API endpoint not found.', {
- handler: 'api-dispatch',
- detail: `No handler for ${method} ${url}`,
- });
- }
+ // The natively-routed link/graph read group (`http/link-graph-routes.ts`).
+ // Its paths live in the Hono app only — deliberately absent from `routes`
+ // above (a route lives in exactly one router). The handle rides the same
+ // shared pipeline with the group's own table, so gate behavior is identical
+ // to the legacy dispatch by construction.
+ const linkGraphRoutes = createLinkGraphRoutes({
+ hocuspocus,
+ derivedDocumentIndex,
+ getFileIndex,
+ isSafeDocName,
+ readPageTitleForDocName,
+ readPageTitleForLinkedDocName,
+ readFrontmatterMetadataForLinkedDocName,
+ collectAdmittedDocNames,
+ resolveAlias,
+ respondToDerivedIndexQueryFailure,
+ });
+ // "A route lives in exactly one router" — enforced at construction, not
+ // just documented; covers every future group aggregated into the native
+ // paths. Throw semantics pinned in `http/http-app.test.ts`.
+ assertSingleRouterOwnership(linkGraphRoutes.paths, routes);
+ const nativeApi: NativeApiHandle = {
+ paths: linkGraphRoutes.paths,
+ dispatch: createApiRequestPipeline({
+ log,
+ remotePublicHost,
+ ephemeral,
+ table: linkGraphRoutes.table,
+ }),
+ };
- const status = response.statusCode;
- span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, status);
- if (status >= 500) {
- span.setStatus({ code: SpanStatusCode.ERROR, message: `status ${status}` });
- }
- } catch (err) {
- span.recordException(err as Error);
- span.setStatus({
- code: SpanStatusCode.ERROR,
- message: err instanceof Error ? err.message : String(err),
- });
- // Last-resort RFC 9457 envelope. Per-handler try/catch is the
- // primary error boundary, but a synchronous throw before any
- // response write would otherwise reach the client as a
- // connection reset (or Hocuspocus default error handling) —
- // not the typed application/problem+json envelope SDK
- // consumers parse. Guard on
- // `!headersSent && !writableEnded && !destroyed` so we
- // don't double-emit when the inner handler already wrote a
- // response or the socket was destroyed mid-handler — same
- // three-way guard `createStreamingErrorWriter` uses for
- // mid-stream emission. Handler tag is the matched route
- // template so telemetry attributes a 5xx surge to the
- // failing endpoint.
- if (!response.headersSent && !response.writableEnded && !response.destroyed) {
- errorResponse(
- response,
- 500,
- 'urn:ok:error:internal-server-error',
- 'Internal server error.',
- {
- handler: routeTemplate,
- cause: err,
- },
- );
- }
- // Re-throw so Hocuspocus's onRequest extension chain logs the
- // exception via its built-in error machinery. The response is
- // already ended (either by errorResponse above or by an
- // earlier handler write), so Hocuspocus 4.x treats this as a
- // post-response observation, not a connection-level failure.
- // Verify this assumption holds when bumping Hocuspocus —
- // version-specific reaction to throws from onRequest is
- // framework-internal behavior.
- throw err;
- } finally {
- span.end();
- const durSec = (Date.now() - started) / 1000;
- httpDurationHist().record(durSec, {
- [ATTR_HTTP_REQUEST_METHOD]: method,
- [ATTR_HTTP_ROUTE]: routeTemplate,
- [ATTR_HTTP_RESPONSE_STATUS_CODE]: response.statusCode,
- });
- }
- },
- ),
- );
+ return {
+ priority: 100, // Higher priority — API routes run before static file serving
+ async onRequest({ request, response }: { request: IncomingMessage; response: ServerResponse }) {
+ await runApiPipeline(request, response);
},
+ nativeApi,
};
}
diff --git a/packages/server/src/api-link-graph-composition.test.ts b/packages/server/src/api-link-graph-composition.test.ts
new file mode 100644
index 000000000..d4b3964e9
--- /dev/null
+++ b/packages/server/src/api-link-graph-composition.test.ts
@@ -0,0 +1,134 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';
+
+/**
+ * Characterization: the natively-routed link/graph read group over a REAL
+ * socket through the composed `bootServer` stack. These routes left the
+ * legacy dispatch registry when they moved to the Hono mount, so a 200 here
+ * is proof of native serving — a wiring gap would surface as the legacy
+ * dispatch's 404. The admission-gate pins mirror
+ * `api-admission-composition.test.ts` on a ported route, closing the exact
+ * bypass the native mount exists to prevent.
+ */
+
+let tmpRoot: string;
+let normal: BootedServer;
+let ephemeral: BootedServer;
+
+beforeAll(async () => {
+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-linkgraph-native-'));
+
+ const normalDir = mkdtempSync(resolve(tmpRoot, 'normal-'));
+ writeFileSync(resolve(normalDir, 'alpha.md'), '# Alpha\n\nLinks to [[beta]].\n', 'utf-8');
+ writeFileSync(resolve(normalDir, 'beta.md'), '# Beta\n\nBody.\n', 'utf-8');
+ normal = await bootCompositionRig(normalDir);
+ await normal.ready;
+
+ const ephemeralDir = mkdtempSync(resolve(tmpRoot, 'ephemeral-'));
+ writeFileSync(resolve(ephemeralDir, 'note.md'), '# note\n', 'utf-8');
+ ephemeral = await bootCompositionRig(ephemeralDir, {
+ ephemeral: true,
+ singleDocRelPath: 'note.md',
+ });
+ await ephemeral.ready;
+}, 60_000);
+
+afterAll(async () => {
+ await Promise.allSettled([normal?.destroy(), ephemeral?.destroy()]);
+ await rm(tmpRoot, { recursive: true, force: true });
+});
+
+describe('link/graph group over the composed listener — served natively', () => {
+ test('every static route in the group answers (absent from the legacy registry)', async () => {
+ for (const path of [
+ '/api/backlinks?docName=beta',
+ '/api/backlink-counts?docNames=alpha,beta',
+ '/api/forward-links?docName=alpha',
+ '/api/link-graph',
+ '/api/dead-links',
+ '/api/tags',
+ '/api/suggest-links?docName=alpha',
+ ]) {
+ const res = await fetch(`http://127.0.0.1:${normal.port}${path}`);
+ expect(res.status, path).toBe(200);
+ expect(res.headers.get('content-type'), path).toBe('application/json');
+ expect(res.headers.get('x-request-id'), path).not.toBeNull();
+ }
+ });
+
+ test('the parametric tags route answers; the empty tail 404s under the typed envelope', async () => {
+ const named = await fetch(`http://127.0.0.1:${normal.port}/api/tags/some-tag`);
+ expect(named.status).toBe(200);
+
+ const empty = await fetch(`http://127.0.0.1:${normal.port}/api/tags/`);
+ expect(empty.status).toBe(404);
+ expect(empty.headers.get('content-type')).toBe('application/problem+json');
+ expect(((await empty.json()) as { type?: string }).type).toBe('urn:ok:error:not-found');
+ });
+
+ test('method gate holds on the native mount (POST answers 405 + Allow: GET)', async () => {
+ const res = await fetch(`http://127.0.0.1:${normal.port}/api/backlinks`, { method: 'POST' });
+ expect(res.status).toBe(405);
+ expect(res.headers.get('allow')).toBe('GET');
+ });
+
+ test('foreign Origin is refused before dispatch on a ported route', async () => {
+ const res = await fetch(`http://127.0.0.1:${normal.port}/api/backlinks?docName=beta`, {
+ headers: { Origin: 'https://evil.example' },
+ });
+ expect(res.status).toBe(403);
+ const body = (await res.json()) as { type?: string };
+ expect(body.type).toBe('urn:ok:error:invalid-origin');
+ });
+
+ test('allowed browser Origin gets CORS reflection on a ported route', async () => {
+ const res = await fetch(`http://127.0.0.1:${normal.port}/api/backlinks?docName=beta`, {
+ headers: { Origin: 'http://localhost:5173' },
+ });
+ expect(res.status).toBe(200);
+ expect(res.headers.get('access-control-allow-origin')).toBe('http://localhost:5173');
+ expect(res.headers.get('vary')).toContain('Origin');
+ });
+
+ test('OPTIONS preflight answers 204 on a ported route', async () => {
+ const res = await fetch(`http://127.0.0.1:${normal.port}/api/backlinks`, {
+ method: 'OPTIONS',
+ headers: { Origin: 'http://localhost:5173' },
+ });
+ expect(res.status).toBe(204);
+ expect(res.headers.get('access-control-allow-methods')).toBe('GET, POST, PUT, DELETE, OPTIONS');
+ });
+
+ test('any forwarding header trips the proxied-request refusal on a ported route', async () => {
+ const res = await rawRequest(normal.port, '/api/backlinks?docName=beta', {
+ headers: { 'X-Forwarded-For': '203.0.113.7' },
+ });
+ expect(res.status).toBe(403);
+ const body = parseProblem(res.body);
+ expect(body.type).toBe('urn:ok:error:host-not-allowed');
+ 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.
+ const res = await rawRequest(normal.port, '/api/backlinks?docName=beta', {
+ headers: { Host: 'evil.example' },
+ });
+ expect(res.status).toBe(200);
+ });
+
+ test('ephemeral mode Host-gates the ported reads too', async () => {
+ const res = await rawRequest(ephemeral.port, '/api/backlinks?docName=note', {
+ headers: { Host: 'evil.example' },
+ });
+ expect(res.status).toBe(403);
+ expect(parseProblem(res.body).type).toBe('urn:ok:error:host-not-allowed');
+ });
+});
diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.ts
index 872ca67e4..204f5f555 100644
--- a/packages/server/src/boot.ts
+++ b/packages/server/src/boot.ts
@@ -918,6 +918,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {
const mount = mountMcpAndApi({
httpServer,
hocuspocus,
+ nativeApi: serverInstance.nativeApi,
mcpHttpHandler,
remoteAccess,
health: {
diff --git a/packages/server/src/frontmatter-telemetry.ts b/packages/server/src/frontmatter-telemetry.ts
index c2fe60936..b1b440b64 100644
--- a/packages/server/src/frontmatter-telemetry.ts
+++ b/packages/server/src/frontmatter-telemetry.ts
@@ -3,7 +3,7 @@
*
* Lazy-init meter so registration runs against a real provider post-
* `initTelemetry` (not the pre-init no-op). Same pattern as
- * `api-extension.ts:httpDurationHist` and
+ * `http/api-pipeline.ts:httpDurationHist` and
* `file-watcher.ts:_fileWatcherEventsCounter`. Co-located here so all
* edit-surface sites (`applyAgentMarkdownWrite`, `applyExternalChange`,
* server-observers Observer B) call into one set of instruments.
diff --git a/packages/server/src/health-routes.test.ts b/packages/server/src/health-routes.test.ts
index 94b1f651b..69af9ff96 100644
--- a/packages/server/src/health-routes.test.ts
+++ b/packages/server/src/health-routes.test.ts
@@ -165,6 +165,7 @@ describe('/readyz provider states (mounted harness)', () => {
const httpServer = createServer();
const mount = mountMcpAndApi({
httpServer,
+ nativeApi: undefined,
hocuspocus: fakeHocuspocus,
log: fakeLog as never,
...(readiness === undefined
@@ -208,6 +209,7 @@ describe('/readyz provider states (mounted harness)', () => {
const httpServer = createServer();
const mount = mountMcpAndApi({
httpServer,
+ nativeApi: undefined,
hocuspocus: fakeHocuspocus,
log: fakeLog as never,
health: {
diff --git a/packages/server/src/http/api-pipeline.test.ts b/packages/server/src/http/api-pipeline.test.ts
new file mode 100644
index 000000000..9fd2a28f8
--- /dev/null
+++ b/packages/server/src/http/api-pipeline.test.ts
@@ -0,0 +1,306 @@
+import { createServer } from 'node:http';
+import { describe, expect, test } from 'vitest';
+import { parseProblem, rawRequest } from '../composition-rig.test-helper.ts';
+import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';
+import { type ApiRouteTable, createApiRequestPipeline } from './api-pipeline.ts';
+import { createHttpApp, type NativeApiHandle } from './http-app.ts';
+
+/**
+ * Gate parity for natively-mounted `/api/*` routes. The composition suite
+ * (`api-admission-composition.test.ts`) pins the admission gates as the
+ * LEGACY dispatch applies them; this suite pins the same wire behavior for
+ * routes mounted ABOVE the strangler catch-all through `NativeApiHandle` —
+ * the exact bypass the native mount exists to close. A synthetic route table
+ * keeps the pins independent of any real route group's handler behavior.
+ */
+
+const fakeLog = {
+ error: () => {},
+ warn: () => {},
+ info: () => {},
+ debug: () => {},
+ child: () => fakeLog,
+} as never;
+
+/** The exact preflight header list the legacy dispatch reflects — byte-pinned. */
+const EXPECTED_ALLOW_HEADERS =
+ 'Content-Type, Authorization, traceparent, tracestate, baggage, x-request-id, x-ok-client-protocol, x-ok-client-runtime, x-ok-client-kind';
+
+interface NativeRig {
+ port: number;
+ baseUrl: string;
+ legacyCalls: string[];
+ close: () => Promise<void>;
+}
+
+async function bootNativeRig(opts: { ephemeral?: boolean } = {}): Promise<NativeRig> {
+ const legacyCalls: string[] = [];
+ const table: ApiRouteTable = {
+ resolve(pathname) {
+ if (pathname === '/api/native-ping' || pathname === '/api/native-mutating') {
+ return {
+ template: pathname,
+ dispatch: async (_req, res) => {
+ res.writeHead(200, { 'Content-Type': 'application/json' });
+ res.end(JSON.stringify({ pong: true }));
+ },
+ };
+ }
+ if (pathname === '/api/native-throw') {
+ return {
+ template: pathname,
+ dispatch: async () => {
+ throw new Error('handler boom');
+ },
+ };
+ }
+ // Owned prefix with no handler — the pipeline's 404 must close it.
+ if (pathname === '/api/native-empty') {
+ return { template: '/api/native-empty' };
+ }
+ return null;
+ },
+ isMutating: (pathname) => pathname === '/api/native-mutating',
+ };
+ const nativeApi: NativeApiHandle = {
+ paths: [
+ '/api/native-ping',
+ '/api/native-mutating',
+ '/api/native-throw',
+ '/api/native-empty',
+ // Claimed by the router but declined by the table — must fall through
+ // to the legacy dispatch.
+ '/api/native-declined',
+ ],
+ dispatch: createApiRequestPipeline({
+ log: fakeLog,
+ ephemeral: opts.ephemeral,
+ table,
+ }),
+ };
+ const { requestListener } = createHttpApp({
+ nativeApi,
+ legacyDispatch: (req, res) => {
+ legacyCalls.push(req.url ?? '');
+ res.writeHead(299, { 'Content-Type': 'text/plain' });
+ res.end('legacy');
+ },
+ log: fakeLog,
+ });
+ const server = createServer(requestListener);
+ const { port, baseUrl } = await listenOnLoopback(server);
+ return {
+ port,
+ baseUrl,
+ legacyCalls,
+ close: () =>
+ new Promise<void>((resolvePromise, reject) => {
+ server.close((err) => (err ? reject(err) : resolvePromise()));
+ }),
+ };
+}
+
+describe('natively-mounted /api routes run the shared admission pipeline', () => {
+ test('a claimed route is served natively — the legacy dispatch never sees it', async () => {
+ const rig = await bootNativeRig();
+ try {
+ const res = await fetch(`${rig.baseUrl}/api/native-ping`);
+ expect(res.status).toBe(200);
+ expect(await res.json()).toEqual({ pong: true });
+ expect(rig.legacyCalls).toEqual([]);
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('an unclaimed route still flows through the legacy dispatch', async () => {
+ const rig = await bootNativeRig();
+ try {
+ const res = await fetch(`${rig.baseUrl}/api/anything-else`);
+ expect(res.status).toBe(299);
+ expect(rig.legacyCalls).toEqual(['/api/anything-else']);
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('a claimed path the table declines falls through to the legacy dispatch', async () => {
+ const rig = await bootNativeRig();
+ try {
+ const res = await fetch(`${rig.baseUrl}/api/native-declined`);
+ expect(res.status).toBe(299);
+ expect(rig.legacyCalls).toEqual(['/api/native-declined']);
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('a dot-segment URL the router normalizes onto a claimed path still gets a response', async () => {
+ const rig = await bootNativeRig();
+ try {
+ // Hono matches `/api/./native-ping` against the claimed path (the
+ // adapter normalizes dot segments), but the pipeline resolves the RAW
+ // req.url and declines it — the fall-through must hand the request to
+ // the legacy dispatch rather than leaving it unanswered.
+ const res = await rawRequest(rig.port, '/api/./native-ping', {});
+ expect(res.status).toBe(299);
+ expect(rig.legacyCalls).toEqual(['/api/./native-ping']);
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('responses carry the x-request-id echo, honoring a well-formed inbound ID', async () => {
+ const rig = await bootNativeRig();
+ try {
+ const minted = await fetch(`${rig.baseUrl}/api/native-ping`);
+ expect(minted.headers.get('x-request-id')).toMatch(/^[A-Za-z0-9._-]{1,128}$/);
+
+ const echoed = await fetch(`${rig.baseUrl}/api/native-ping`, {
+ headers: { 'x-request-id': 'caller-chosen.id-42' },
+ });
+ expect(echoed.headers.get('x-request-id')).toBe('caller-chosen.id-42');
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('a foreign Origin is refused before dispatch with the legacy problem shape', async () => {
+ const rig = await bootNativeRig();
+ try {
+ const res = await fetch(`${rig.baseUrl}/api/native-ping`, {
+ headers: { Origin: 'https://evil.example' },
+ });
+ expect(res.status).toBe(403);
+ expect(res.headers.get('content-type')).toBe('application/problem+json');
+ const body = (await res.json()) as { type?: string; title?: string };
+ expect(body.type).toBe('urn:ok:error:invalid-origin');
+ expect(body.title).toBe('Origin not allowed.');
+ // The rejection still carries the request-id echo (identity slots
+ // BEFORE the gates).
+ expect(res.headers.get('x-request-id')).not.toBeNull();
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('an allowed browser Origin gets verbatim CORS reflection with the exact header list', async () => {
+ const rig = await bootNativeRig();
+ try {
+ const res = await fetch(`${rig.baseUrl}/api/native-ping`, {
+ headers: { Origin: 'http://localhost:5173' },
+ });
+ expect(res.status).toBe(200);
+ expect(res.headers.get('access-control-allow-origin')).toBe('http://localhost:5173');
+ expect(res.headers.get('vary')).toContain('Origin');
+ expect(res.headers.get('access-control-allow-methods')).toBe(
+ 'GET, POST, PUT, DELETE, OPTIONS',
+ );
+ expect(res.headers.get('access-control-allow-headers')).toBe(EXPECTED_ALLOW_HEADERS);
+ expect(res.headers.get('access-control-expose-headers')).toBe('x-request-id');
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('OPTIONS preflight answers 204 with the CORS headers', async () => {
+ const rig = await bootNativeRig();
+ try {
+ const res = await fetch(`${rig.baseUrl}/api/native-ping`, {
+ method: 'OPTIONS',
+ headers: { Origin: 'http://localhost:5173' },
+ });
+ expect(res.status).toBe(204);
+ expect(res.headers.get('access-control-allow-methods')).toBe(
+ 'GET, POST, PUT, DELETE, OPTIONS',
+ );
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('any forwarding header trips the proxied-request refusal on a native route', async () => {
+ const rig = await bootNativeRig();
+ try {
+ const res = await rawRequest(rig.port, '/api/native-ping', {
+ headers: { 'X-Forwarded-For': '203.0.113.7' },
+ });
+ expect(res.status).toBe(403);
+ const body = parseProblem(res.body);
+ expect(body.type).toBe('urn:ok:error:host-not-allowed');
+ expect(body.detail ?? body.title).toContain('Proxied request refused');
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('a mutating native route under a rebound Host is refused; a read route answers', async () => {
+ const rig = await bootNativeRig();
+ try {
+ const refused = await rawRequest(rig.port, '/api/native-mutating', {
+ headers: { Host: 'evil.example' },
+ });
+ 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.
+ const read = await rawRequest(rig.port, '/api/native-ping', {
+ headers: { Host: 'evil.example' },
+ });
+ expect(read.status).toBe(200);
+
+ const allowed = await rawRequest(rig.port, '/api/native-mutating', {
+ headers: { Host: 'localhost' },
+ });
+ expect(allowed.status).toBe(200);
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('ephemeral mode Host-gates EVERY native /api route, including reads', async () => {
+ const rig = await bootNativeRig({ ephemeral: true });
+ try {
+ const refused = await rawRequest(rig.port, '/api/native-ping', {
+ headers: { Host: 'evil.example' },
+ });
+ expect(refused.status).toBe(403);
+ expect(parseProblem(refused.body).type).toBe('urn:ok:error:host-not-allowed');
+
+ const allowed = await rawRequest(rig.port, '/api/native-ping', {
+ headers: { Host: 'localhost' },
+ });
+ expect(allowed.status).toBe(200);
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('an owned URL with no handler gets the explicit RFC 9457 404', async () => {
+ const rig = await bootNativeRig();
+ try {
+ const res = await fetch(`${rig.baseUrl}/api/native-empty`);
+ expect(res.status).toBe(404);
+ expect(res.headers.get('content-type')).toBe('application/problem+json');
+ const body = (await res.json()) as { type?: string; title?: string };
+ expect(body.type).toBe('urn:ok:error:not-found');
+ expect(body.title).toBe('API endpoint not found.');
+ expect(rig.legacyCalls).toEqual([]);
+ } finally {
+ await rig.close();
+ }
+ });
+
+ test('a throwing handler surfaces as the typed 500 envelope, not a reset', async () => {
+ const rig = await bootNativeRig();
+ try {
+ const res = await fetch(`${rig.baseUrl}/api/native-throw`);
+ expect(res.status).toBe(500);
+ expect(res.headers.get('content-type')).toBe('application/problem+json');
+ const body = (await res.json()) as { type?: string };
+ expect(body.type).toBe('urn:ok:error:internal-server-error');
+ } finally {
+ await rig.close();
+ }
+ });
+});
diff --git a/packages/server/src/http/api-pipeline.ts b/packages/server/src/http/api-pipeline.ts
new file mode 100644
index 000000000..84d67b8fc
--- /dev/null
+++ b/packages/server/src/http/api-pipeline.ts
@@ -0,0 +1,453 @@
+/**
+ * The `/api/*` admission pipeline — request identity, CORS, DNS-rebinding
+ * gates, and the OTel dispatch span — shared by BOTH routers during the
+ * strangler migration.
+ *
+ * The pipeline used to live inline in `api-extension.ts`'s `onRequest` hook.
+ * Native routes mounted on the canonical Hono app sit ABOVE the strangler
+ * catch-all and therefore bypass that hook entirely — safe for the health
+ * probes, a security regression for `/api/*`. Extracting the pipeline and
+ * dispatching both routers through it makes byte parity structural: one
+ * implementation, two route tables. When the legacy dispatch handles nothing,
+ * its table is deleted and the pipeline keeps running for the native one.
+ *
+ * The gate ORDER is load-bearing and mirrors the historical hook exactly:
+ *
+ * 1. embed-probe observation (ring buffer drained by `/api/__embed-detect`)
+ * 2. request-id resolve + echo + `api.access` log wiring — BEFORE the gates
+ * 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
+ * 6. OTel server span wrapping dispatch, the unmatched-route 404, and the
+ * duration histogram
+ *
+ * NOT part of this pipeline: the proxied-request tripwire and the remote-admit
+ * Host gate. Those are surface-wide (`/mcp`, static assets, the SPA) and live
+ * with the mount (`admitRequestSurface` in `http-app.ts`); the Vite dev server
+ * never applied them and must keep not applying them.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { CLIENT_VERSION_HEADER } from '@inkeep/open-knowledge-core';
+import { context, propagation, SpanKind, SpanStatusCode } from '@opentelemetry/api';
+import {
+ ATTR_HTTP_REQUEST_METHOD,
+ ATTR_HTTP_RESPONSE_STATUS_CODE,
+ ATTR_HTTP_ROUTE,
+ ATTR_URL_PATH,
+ ATTR_URL_SCHEME,
+ ATTR_USER_AGENT_ORIGINAL,
+} from '@opentelemetry/semantic-conventions';
+import { isAllowedApiOrigin } from '../api-origin.ts';
+import { recordEmbedProbe } from '../embed-probe.ts';
+import type { PinoLogger } from '../logger.ts';
+import {
+ isAllowedWorkspaceHostHeader as isAllowedWorkspaceHostHeaderBase,
+ isLoopbackAddress,
+} from '../loopback.ts';
+import { hostHeaderMatchesPublicHost } from '../remote-access.ts';
+import { getMeter, getTracer, onTelemetryShutdown } from '../telemetry.ts';
+import { errorResponse } from './error-response.ts';
+import { REQUEST_ID_HEADER, rememberRequestId, resolveRequestId } from './request-id.ts';
+
+/** Outcome of resolving a pathname against a route table. */
+interface ApiRouteResolution {
+ /**
+ * Low-cardinality route TEMPLATE for the access log, span name, and
+ * duration-histogram labels (`/api/tags/:name`, never the raw path) —
+ * cardinality discipline for log aggregators and metric labels.
+ */
+ template: string;
+ /**
+ * Bound dispatch for the matched handler. Absent means the table owns the
+ * URL but nothing handles it (empty `/api/history/` segment, unregistered
+ * route) — the pipeline emits the explicit RFC 9457 404 after the gates.
+ */
+ dispatch?: ((req: IncomingMessage, res: ServerResponse) => Promise<void>) | undefined;
+}
+
+/**
+ * A router's view of its `/api/*` routes. Two implementations exist during
+ * the migration: the legacy dispatch record in `api-extension.ts` (which
+ * never declines a URL — unmatched resolves to the `/api/*` template with no
+ * dispatch so the pipeline's 404 owns the response) and the native route
+ * group (which declines URLs it has not claimed so the caller can fall
+ * through to the legacy dispatch with zero side effects).
+ */
+export interface ApiRouteTable {
+ resolve(pathname: string): ApiRouteResolution | null;
+ /** Membership in the loopback + workspace-Host mutating gate. */
+ isMutating(pathname: string): boolean;
+}
+
+export interface ApiPipelineOptions {
+ log: PinoLogger;
+ /**
+ * The tunnel's public host when the server was started with remote access
+ * enabled. Widens the browser-Origin allowlist and the workspace-Host
+ * predicate the same way the api-extension's local shadows do.
+ */
+ remotePublicHost?: string;
+ /** No-project ephemeral single-file mode — gates EVERY `/api/*` request. */
+ ephemeral?: boolean;
+ table: ApiRouteTable;
+}
+
+/**
+ * Returns `true` when the pipeline owned the request (response written or
+ * handler dispatched), `false` when the table declined the URL — the caller
+ * then falls through to its next dispatch layer. Rejects when a handler
+ * throws (the RFC 9457 500 is already on the wire; callers log and move on).
+ */
+export type ApiRequestPipeline = (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+
+// Cache the HTTP duration histogram at module scope — lazy-init at first use
+// so the meter is a real meter (post-`initTelemetry`), not the pre-init no-op.
+// Recreating the histogram every request allocates + registers a fresh
+// instrument on every hit.
+let _httpDurationHist: ReturnType<ReturnType<typeof getMeter>['createHistogram']> | null = null;
+// Reset on provider teardown so a shutdownTelemetry + initTelemetry cycle
+// (dev-server restart, test harness) re-registers against the fresh provider
+// instead of silently recording into the dead one. Same pattern as
+// `parse-pool.ts`.
+onTelemetryShutdown(() => {
+ _httpDurationHist = null;
+});
+function httpDurationHist(): ReturnType<ReturnType<typeof getMeter>['createHistogram']> {
+ _httpDurationHist ||= getMeter().createHistogram('http.server.request.duration', {
+ description: 'HTTP server request duration in seconds',
+ unit: 's',
+ });
+ return _httpDurationHist;
+}
+
+export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPipeline {
+ const { log, remotePublicHost, ephemeral, table } = opts;
+ // In remote mode the tunnel's public Host is as legitimate as a loopback
+ // name — the mount's admit gate already vetted it. Same widening the
+ // api-extension applies to its route-level Host gates.
+ const isAllowedWorkspaceHostHeader = (host: string | undefined): boolean =>
+ isAllowedWorkspaceHostHeaderBase(host) ||
+ (remotePublicHost !== undefined && hostHeaderMatchesPublicHost(host, remotePublicHost));
+
+ return async (request, response) => {
+ const url = request.url?.split('?')[0];
+ if (!url) return false;
+
+ const resolution = table.resolve(url);
+ if (!resolution) return false;
+
+ // Per-request client-context observation for embed-detection spikes.
+ // Pushed into a bounded in-process ring buffer drained by
+ // /api/__embed-detect. Assumes loopback-only deployment — the consumer
+ // endpoint enforces this. Multi-valued headers (rare) collapse to the
+ // joined string Node provides by default for the headers we capture.
+ const headerString = (name: string): string | undefined => {
+ const value = request.headers[name];
+ if (value === undefined) return undefined;
+ return Array.isArray(value) ? value.join(', ') : value;
+ };
+ recordEmbedProbe({
+ ts: Date.now(),
+ url,
+ method: request.method ?? '',
+ ua: headerString('user-agent'),
+ origin: headerString('origin'),
+ referer: headerString('referer'),
+ host: headerString('host'),
+ remote: request.socket?.remoteAddress,
+ secChUa: headerString('sec-ch-ua'),
+ secChUaMobile: headerString('sec-ch-ua-mobile'),
+ secChUaPlatform: headerString('sec-ch-ua-platform'),
+ secFetchSite: headerString('sec-fetch-site'),
+ secFetchDest: headerString('sec-fetch-dest'),
+ secFetchMode: headerString('sec-fetch-mode'),
+ secFetchUser: headerString('sec-fetch-user'),
+ });
+
+ const method = request.method ?? 'GET';
+ const routeTemplate = resolution.template;
+
+ // Request identity + access log for the /api/* surface. Slots BEFORE the
+ // origin/loopback/host gates (without touching their order) so even
+ // gate-rejected responses carry the `x-request-id` echo and produce an
+ // access-log line. The `typeof` guards mirror the CORS block below —
+ // unit-test doubles stub only `writeHead` + `end`.
+ const requestId = url.startsWith('/api/') ? resolveRequestId(request) : undefined;
+ if (requestId !== undefined) {
+ rememberRequestId(request, requestId);
+ if (typeof response.setHeader === 'function') {
+ response.setHeader(REQUEST_ID_HEADER, requestId);
+ }
+ if (typeof response.once === 'function') {
+ const accessStarted = Date.now();
+ let accessLogged = false;
+ // One line per request on whichever of finish/close fires first:
+ // 'finish' is the fully-flushed response (including long-lived
+ // NDJSON streams, logged at stream end); 'close' catches aborted
+ // sockets (client disconnect, timeout destroy) that never finish.
+ // Route TEMPLATE, never the raw path — cardinality discipline for
+ // log aggregators matches the metric-label STOP rule. Byte counts
+ // are omitted: Node exposes no cheap per-response counter under
+ // chunked encoding (socket.bytesWritten is per-connection).
+ const emitAccessLog = () => {
+ if (accessLogged) return;
+ accessLogged = true;
+ log.info(
+ {
+ event: 'api.access',
+ requestId,
+ method,
+ route: routeTemplate,
+ status: response.statusCode,
+ durationMs: Date.now() - accessStarted,
+ ...(response.writableFinished ? {} : { aborted: true }),
+ },
+ `${method} ${routeTemplate} ${response.statusCode}`,
+ );
+ };
+ response.once('finish', emitAccessLog);
+ response.once('close', emitAccessLog);
+ }
+ }
+
+ // Origin-allowlist CORS for /api/*. Only loopback origins are accepted:
+ // - No Origin header (same-origin browser tab, curl, CLI): passes through.
+ // - Origin "null" (Electron packaged renderer, file:// per Fetch spec §4.3): allowed.
+ // - http(s)://localhost[:port] / 127.x.x.x[:port] / [::1][:port]: allowed.
+ // - Any other Origin: 403 — closes the CSRF door on unauthenticated mutating
+ // routes (/api/agent-write-md, /api/rollback, /api/manage/delete, etc.)
+ // without breaking the Electron renderer or local Vite dev servers.
+ //
+ // When an allowed Origin is present, it is reflected verbatim in ACAO (not
+ // `*`) so the browser's preflight check passes while non-loopback origins are
+ // still refused by the gate above. `Vary: Origin` prevents cache poisoning.
+ //
+ // Setting via `setHeader` (not `writeHead`) so handler responses that call
+ // `writeHead(status, { ... })` inherit these headers. The typeof guard handles
+ // unit tests that stub only `writeHead` + `end`.
+ if (url.startsWith('/api/')) {
+ const origin = request.headers.origin;
+ if (origin !== undefined && !isAllowedApiOrigin(origin, remotePublicHost)) {
+ // RFC 9457 problem+json. Tag the handler as `api-origin-gate` so
+ // the `ok.api.error.count` counter distinguishes onRequest-level
+ // CSRF rejections from per-handler emits. The cross-origin browser
+ // can't read the body anyway (CORS strips it) but consistent wire
+ // shape lets server-to-server callers + tests parse uniformly.
+ errorResponse(response, 403, 'urn:ok:error:invalid-origin', 'Origin not allowed.', {
+ handler: 'api-origin-gate',
+ });
+ return true;
+ }
+ if (typeof response.setHeader === 'function') {
+ if (origin !== undefined) {
+ response.setHeader('Access-Control-Allow-Origin', origin);
+ response.setHeader('Vary', 'Origin');
+ }
+ response.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+ // Content-Type/Authorization: standard request headers. traceparent/
+ // tracestate/baggage: OTel W3C trace-context propagation from the
+ // browser SDK. x-ok-client-*: the client→version metadata the renderer
+ // stamps on every /api/* request (clientVersionHeaders) — omitting
+ // these fails the preflight for the cross-origin renderer (dev Vite
+ // origin / file:// packaged) before the real request fires.
+ response.setHeader(
+ 'Access-Control-Allow-Headers',
+ `Content-Type, Authorization, traceparent, tracestate, baggage, ${REQUEST_ID_HEADER}, ${CLIENT_VERSION_HEADER.protocol}, ${CLIENT_VERSION_HEADER.runtime}, ${CLIENT_VERSION_HEADER.kind}`,
+ );
+ // Let cross-origin renderer JS read the correlation ID echo — CORS
+ // hides non-safelisted response headers by default.
+ response.setHeader('Access-Control-Expose-Headers', REQUEST_ID_HEADER);
+ }
+ // OPTIONS preflight — short-circuit with 204 + the headers above.
+ if (request.method === 'OPTIONS') {
+ response.writeHead(204);
+ response.end();
+ return true;
+ }
+ }
+
+ // DNS-rebinding defense for state-mutating endpoints. The
+ // `isLoopbackAddress` TCP-peer check and `isAllowedWorkspaceHostHeader`
+ // Host-header check together block the standard rebinding pattern
+ // (attacker-owned hostname whose DNS resolves to 127.0.0.1 after an
+ // initial attacker-serves-JS response — the TCP peer is loopback,
+ // but the Host header names the attacker domain). The same mitigation
+ // already gates `/api/workspace`; without it, a rebinding page could
+ // POST /api/upload + /api/agent-write, mutating the local vault.
+ //
+ // Test-harness note: Node's production socket always has
+ // `remoteAddress` set by the kernel; the only path that reaches
+ // this check without a socket is a mocked `IncomingMessage` built
+ // from `Readable.from(...)`. Those mocks bypass the HTTP listener
+ // entirely and can't be reached by a real remote attacker, so a
+ // missing socket is treated as test-context and skips the check.
+ // The Host-header gate still fires (tests set `host: 'localhost'`),
+ // so the protection remains meaningful for any production path.
+ if (table.isMutating(url)) {
+ const peerAddress = request.socket?.remoteAddress;
+ if (peerAddress !== undefined && !isLoopbackAddress(peerAddress)) {
+ errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
+ handler: 'api-mutating-gate',
+ });
+ return true;
+ }
+ if (!isAllowedWorkspaceHostHeader(request.headers.host)) {
+ errorResponse(response, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
+ handler: 'api-mutating-gate',
+ });
+ 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/')) {
+ const peerAddress = request.socket?.remoteAddress;
+ if (peerAddress !== undefined && !isLoopbackAddress(peerAddress)) {
+ errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
+ handler: 'api-ephemeral-gate',
+ });
+ return true;
+ }
+ if (!isAllowedWorkspaceHostHeader(request.headers.host)) {
+ errorResponse(response, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
+ handler: 'api-ephemeral-gate',
+ });
+ return true;
+ }
+ }
+
+ // Only /api/* gets a server span. Non-API routes (static file serving,
+ // Hocuspocus's own paths) fall through silently. (Route dispatch
+ // happens inside the OTel active-span block below.)
+ if (!url.startsWith('/api/')) return false;
+
+ // Extract incoming trace context (W3C traceparent header) so this server
+ // span attaches as a child of the browser-initiated trace.
+ const extractedCtx = propagation.extract(context.active(), request.headers);
+
+ const tracer = getTracer();
+ const started = Date.now();
+ await context.with(extractedCtx, () =>
+ tracer.startActiveSpan(
+ `HTTP ${method} ${routeTemplate}`,
+ {
+ kind: SpanKind.SERVER,
+ attributes: {
+ [ATTR_HTTP_REQUEST_METHOD]: method,
+ [ATTR_HTTP_ROUTE]: routeTemplate,
+ [ATTR_URL_PATH]: url,
+ [ATTR_URL_SCHEME]: 'http',
+ [ATTR_USER_AGENT_ORIGINAL]: request.headers['user-agent'] ?? '',
+ // Correlation ID (UUID or client-supplied bounded token) — a
+ // sanctioned span attribute like `ok.error.instance`; the
+ // cardinality STOP rule governs metric labels, which stay
+ // request-id-free.
+ 'ok.request.id': requestId,
+ },
+ },
+ async (span) => {
+ try {
+ const dispatch = resolution.dispatch;
+ if (dispatch !== undefined) {
+ await dispatch(request, response);
+ } else {
+ // Defense-in-depth: unmatched `/api/*` routes (typos, removed
+ // endpoints, empty `/api/rescue/` / `/api/history/` segments)
+ // would otherwise fall through with no response body, leaving
+ // Hocuspocus's `onRequest` machinery to either pass through to
+ // static-file middleware or hang. Emit an explicit RFC 9457 404
+ // so the dispatch surface is fully closed.
+ //
+ // `detail` echoes the actual requested URL (no information
+ // leak — the client sent it). `routeTemplate` is bounded
+ // to `/api/*` for unmatched routes and used only for
+ // histogram labels / span attributes upstream — keeping
+ // the two concerns separate so the wire-detail stays
+ // actionable for debuggers without coupling to the
+ // cardinality-bounded telemetry surface.
+ errorResponse(response, 404, 'urn:ok:error:not-found', 'API endpoint not found.', {
+ handler: 'api-dispatch',
+ detail: `No handler for ${method} ${url}`,
+ });
+ }
+
+ const status = response.statusCode;
+ span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, status);
+ if (status >= 500) {
+ span.setStatus({ code: SpanStatusCode.ERROR, message: `status ${status}` });
+ }
+ } catch (err) {
+ span.recordException(err as Error);
+ span.setStatus({
+ code: SpanStatusCode.ERROR,
+ message: err instanceof Error ? err.message : String(err),
+ });
+ // Last-resort RFC 9457 envelope. Per-handler try/catch is the
+ // primary error boundary, but a synchronous throw before any
+ // response write would otherwise reach the client as a
+ // connection reset (or Hocuspocus default error handling) —
+ // not the typed application/problem+json envelope SDK
+ // consumers parse. Guard on
+ // `!headersSent && !writableEnded && !destroyed` so we
+ // don't double-emit when the inner handler already wrote a
+ // response or the socket was destroyed mid-handler — same
+ // three-way guard `createStreamingErrorWriter` uses for
+ // mid-stream emission. Handler tag is the matched route
+ // template so telemetry attributes a 5xx surge to the
+ // failing endpoint.
+ if (!response.headersSent && !response.writableEnded && !response.destroyed) {
+ errorResponse(
+ response,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'Internal server error.',
+ {
+ handler: routeTemplate,
+ cause: err,
+ },
+ );
+ }
+ // Error spans carry the HTTP status attribute too (OTel HTTP
+ // server semconv) — the try-path stamp above never ran, and
+ // trace UIs filter error spans by status code.
+ span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, response.statusCode);
+ // Re-throw so the caller's error machinery logs the exception —
+ // the legacy dispatch surfaces it through Hocuspocus's onRequest
+ // extension chain, the native mount through its own catch. The
+ // response is already ended (either by errorResponse above or by
+ // an earlier handler write), so Hocuspocus 4.x treats this as a
+ // post-response observation, not a connection-level failure.
+ // Verify this assumption holds when bumping Hocuspocus —
+ // version-specific reaction to throws from onRequest is
+ // framework-internal behavior.
+ throw err;
+ } finally {
+ span.end();
+ const durSec = (Date.now() - started) / 1000;
+ httpDurationHist().record(durSec, {
+ [ATTR_HTTP_REQUEST_METHOD]: method,
+ [ATTR_HTTP_ROUTE]: routeTemplate,
+ [ATTR_HTTP_RESPONSE_STATUS_CODE]: response.statusCode,
+ });
+ }
+ },
+ ),
+ );
+ return true;
+ };
+}
diff --git a/packages/server/src/http/http-app.test.ts b/packages/server/src/http/http-app.test.ts
index e900d2cfd..739c4e95d 100644
--- a/packages/server/src/http/http-app.test.ts
+++ b/packages/server/src/http/http-app.test.ts
@@ -1,7 +1,11 @@
import { createServer } from 'node:http';
import { describe, expect, test } from 'vitest';
import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';
-import { type CreateHttpAppOptions, createHttpApp } from './http-app.ts';
+import {
+ assertSingleRouterOwnership,
+ type CreateHttpAppOptions,
+ createHttpApp,
+} from './http-app.ts';
/**
* Adapter-boundary pins the composition suite cannot see: these assert
@@ -87,3 +91,34 @@ describe('createHttpApp adapter boundary', () => {
}
});
});
+
+describe('assertSingleRouterOwnership', () => {
+ test('throws when a native path also exists in the legacy record', () => {
+ expect(() =>
+ assertSingleRouterOwnership(['/api/backlinks', '/api/tags/*'], {
+ '/api/backlinks': async () => {},
+ }),
+ ).toThrow(
+ 'route(s) present in both the legacy dispatch record and a native route group: /api/backlinks',
+ );
+ });
+
+ test('throws when a legacy record key falls under a native wildcard namespace', () => {
+ expect(() =>
+ assertSingleRouterOwnership(['/api/tags/*'], {
+ '/api/tags/special': async () => {},
+ }),
+ ).toThrow('/api/tags/special (under a native wildcard)');
+ });
+
+ test('passes for disjoint sets, including a legacy key at the wildcard base', () => {
+ expect(() =>
+ assertSingleRouterOwnership(['/api/backlinks', '/api/tags/*'], {
+ '/api/documents': async () => {},
+ // The base path is OUTSIDE the wildcard's namespace ('/api/tags/*'
+ // claims '/api/tags/…', not '/api/tags' itself).
+ '/api/tags': async () => {},
+ }),
+ ).not.toThrow();
+ });
+});
diff --git a/packages/server/src/http/http-app.ts b/packages/server/src/http/http-app.ts
index 5d7586f59..da294afff 100644
--- a/packages/server/src/http/http-app.ts
+++ b/packages/server/src/http/http-app.ts
@@ -3,6 +3,11 @@ import { getRequestListener, type HttpBindings } from '@hono/node-server';
import { RESPONSE_ALREADY_SENT } from '@hono/node-server/utils/response';
import { Hono } from 'hono';
import type { PinoLogger } from '../logger.ts';
+import {
+ hasForwardingHeaders,
+ isRemoteAdmitted,
+ type ResolvedRemoteAccess,
+} from '../remote-access.ts';
import { errorResponse } from './error-response.ts';
/**
@@ -29,11 +34,116 @@ export interface HealthProvider {
degraded: () => readonly string[];
}
+/**
+ * A router-agnostic bundle of natively-served `/api/*` routes: the Hono
+ * patterns to claim ahead of the strangler catch-all, plus the shared
+ * admission pipeline (`http/api-pipeline.ts`) bound to the native route
+ * table. `dispatch` returns `false` when the table declines the URL — the
+ * mount then falls through to the legacy dispatch. That decline is
+ * reachable: Hono matches against a normalized path (dot segments resolved,
+ * non-reserved percent-escapes decoded) while the pipeline resolves the raw
+ * `req.url`, so requests like `/api/./backlinks` are claimed by the router
+ * and declined by the table.
+ */
+export interface NativeApiHandle {
+ paths: readonly string[];
+ dispatch: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+}
+
+/**
+ * The surface-wide admission prelude every request runs before dispatch —
+ * shared verbatim between the legacy `mcp-mount` dispatch and natively-mounted
+ * `/api/*` routes (which sit above the strangler catch-all and would otherwise
+ * bypass it). Returns `false` after writing the 403 when the request is
+ * refused.
+ *
+ * Gate 1 — tripwire: proxy-forwarding headers on a server that never opted
+ * into remote access mean a tunnel is pointed at us. Refuse with the fix
+ * instruction — the alternative is silently serving a public tunnel with full
+ * local trust, decided by whether the tunnel rewrites Host.
+ *
+ * Gate 2 — with remote access enabled, ONE admit decision covers every
+ * surface (trust-the-tunnel — see remote-access.ts): loopback socket + Host on
+ * the allowlist (loopback names or the tunnel's public host). Refusals are
+ * wrong-Host callers (DNS-rebound pages), not auth failures.
+ *
+ * `handler` is the caller's tag on the `ok.api.error.count` counter for
+ * rejections ('mcp-mount' for the legacy dispatch, 'native-api-surface' for
+ * the native mount) — the primary triage dimension, so refusals attribute to
+ * the surface that actually refused.
+ */
+export function admitRequestSurface(
+ req: IncomingMessage,
+ res: ServerResponse,
+ remoteAccess: ResolvedRemoteAccess | undefined,
+ handler: string,
+): boolean {
+ if (remoteAccess === undefined && hasForwardingHeaders(req)) {
+ errorResponse(
+ res,
+ 403,
+ 'urn:ok:error:host-not-allowed',
+ 'Proxied request refused: this server was not started for remote access. Restart with `ok start --remote` to serve through a tunnel.',
+ { handler },
+ );
+ return false;
+ }
+ if (remoteAccess !== undefined && !isRemoteAdmitted(req, remoteAccess)) {
+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
+ handler,
+ });
+ return false;
+ }
+ return true;
+}
+
+/**
+ * "A route lives in exactly one router" — the mechanical form. A path
+ * claimed by a native group that still has a legacy record entry would
+ * silently shadow it (the native mount dispatches first), leaving
+ * live-looking dead code in the legacy dispatch. Callers invoke this at
+ * construction so the overlap fails the boot instead. Both directions are
+ * checked: a native exact path that is also a legacy record key, and a
+ * legacy record key that falls under a native wildcard's namespace (the
+ * wildcard claims everything below its prefix, so such a key is just as
+ * shadowed as an exact duplicate).
+ */
+export function assertSingleRouterOwnership(
+ nativePaths: readonly string[],
+ legacyRoutes: Readonly<Record<string, unknown>>,
+): void {
+ const doubleRouted = nativePaths.filter((p) => !p.includes('*') && p in legacyRoutes);
+ const wildcardPrefixes = nativePaths.filter((p) => p.endsWith('/*')).map((p) => p.slice(0, -1));
+ const shadowed = Object.keys(legacyRoutes)
+ .filter((key) => wildcardPrefixes.some((prefix) => key.startsWith(prefix)))
+ .map((key) => `${key} (under a native wildcard)`);
+ const conflicts = [...doubleRouted, ...shadowed];
+ if (conflicts.length > 0) {
+ throw new Error(
+ `route(s) present in both the legacy dispatch record and a native route group: ${conflicts.join(', ')}`,
+ );
+ }
+}
+
export interface CreateHttpAppOptions {
/** Readiness provider for /readyz; omitted means always-ready (harnesses with synchronous init). */
health?: HealthProvider;
/** The pre-router dispatch. Every route without a native handler flows through here unchanged. */
legacyDispatch: (req: IncomingMessage, res: ServerResponse) => void;
+ /**
+ * Natively-served `/api/*` routes, mounted ABOVE the strangler catch-all.
+ * Each claimed path runs the same surface admission gates the legacy
+ * dispatch applies (`admitRequestSurface`) and then the shared `/api/*`
+ * pipeline via `dispatch` — so a ported route keeps byte-identical gate
+ * behavior while never reaching the legacy dispatch.
+ */
+ nativeApi?: NativeApiHandle;
+ /**
+ * Resolved `remote:` config for the surface admission gates on native
+ * routes (same value the mount applies to the legacy dispatch). Undefined
+ * ⇒ remote access disabled (the tripwire refuses proxied requests).
+ */
+ remoteAccess?: ResolvedRemoteAccess | undefined;
/** Structured logger for handler errors the router catches. */
log: PinoLogger;
}
@@ -111,6 +221,54 @@ export function createHttpApp(opts: CreateHttpAppOptions): HttpAppHandle {
});
}
+ // Natively-served /api/* routes, ABOVE the strangler catch-all. Each runs
+ // the surface admission gates first (the tripwire + remote-admit pair the
+ // legacy dispatch applies in mcp-mount's onRequest), then the shared
+ // /api/* pipeline — request-id, CORS, DNS-rebinding gates, dispatch span.
+ const nativeApi = opts.nativeApi;
+ if (nativeApi !== undefined) {
+ for (const path of nativeApi.paths) {
+ app.all(path, async (c) => {
+ const req = c.env.incoming;
+ const res = c.env.outgoing;
+ if (!admitRequestSurface(req, res, opts.remoteAccess, 'native-api-surface')) {
+ return RESPONSE_ALREADY_SENT;
+ }
+ try {
+ const handled = await nativeApi.dispatch(req, res);
+ // Reachable: Hono routes on a NORMALIZED path (`@hono/node-server`
+ // resolves dot segments, and strict-mode `getPath` percent-decodes),
+ // while the pipeline re-derives the path from the untouched
+ // `c.env.incoming.url`. So `/api/./backlinks` and `/api/back%6Cinks`
+ // get claimed here and then declined by the table. The legacy
+ // dispatch owns every URL the native table does not; this branch is
+ // what keeps those requests from hanging with no response written.
+ if (!handled) opts.legacyDispatch(req, res);
+ } catch (err) {
+ // Mirrors the legacy dispatch's posture for onRequest rejections:
+ // the pipeline already emitted the typed 500 before rethrowing, so
+ // this is log-only unless the response never started.
+ opts.log.error({ err }, 'Unhandled onRequest error');
+ if (!res.writableEnded && !res.headersSent) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'Internal server error.',
+ {
+ handler: 'native-api-catch',
+ cause: err,
+ },
+ );
+ } else if (!res.writableEnded) {
+ res.end();
+ }
+ }
+ return RESPONSE_ALREADY_SENT;
+ });
+ }
+ }
+
// Strangler catch-all: hand the raw req/res to the legacy dispatch and
// tell the adapter the response is owned elsewhere. The legacy handlers
// finish asynchronously; Node keeps the response open until they end it.
diff --git a/packages/server/src/http/link-graph-routes.ts b/packages/server/src/http/link-graph-routes.ts
new file mode 100644
index 000000000..ea131be65
--- /dev/null
+++ b/packages/server/src/http/link-graph-routes.ts
@@ -0,0 +1,583 @@
+/**
+ * The link/graph read family — `backlinks`, `backlink-counts`,
+ * `forward-links`, `link-graph`, `dead-links`, `tags-list`, `tags-for-name`,
+ * `suggest-links` — lifted out of `api-extension.ts` as the first natively-
+ * routed Wave 2 group. Same lift shape as `skills-sh-handlers.ts`: what the
+ * handlers closed over in the extension arrives as
+ * {@link LinkGraphRouteDeps}, and the handler bodies are unchanged.
+ *
+ * Unlike the skills.sh handlers, this group does NOT return to the legacy
+ * route table: `createLinkGraphRoutes` returns an {@link ApiRouteTable} +
+ * the Hono patterns for the native mount, and the extension exposes them as
+ * its `nativeApi` handle. A route lives in exactly one router — these paths
+ * are gone from the legacy dispatch record in the same change.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Hocuspocus } from '@hocuspocus/server';
+import {
+ BacklinkCountsSuccessSchema,
+ BacklinksSuccessSchema,
+ DeadLinksSuccessSchema,
+ EmptyRequestSchema,
+ ForwardLinksSuccessSchema,
+ LinkGraphSuccessSchema,
+ SuggestLinksSuccessSchema,
+ TagsForNameSuccessSchema,
+ TagsListSuccessSchema,
+} from '@inkeep/open-knowledge-core';
+import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';
+import type { DerivedDocumentIndexApiPort, DerivedGraphNode } from '../derived-document-index.ts';
+import type { FileIndexEntry } from '../file-watcher.ts';
+import type { FrontmatterMetadata } from '../page-identity.ts';
+import { SuggestLinksTargetNotFoundError, suggestLinks } from '../suggest-links.ts';
+import type { ApiRouteTable } from './api-pipeline.ts';
+import { errorResponse } from './error-response.ts';
+import { withValidation } from './request-validation.ts';
+import { successResponse } from './success-response.ts';
+
+export interface LinkGraphRouteDeps {
+ hocuspocus: Hocuspocus;
+ derivedDocumentIndex: DerivedDocumentIndexApiPort | undefined;
+ getFileIndex: () => ReadonlyMap<string, FileIndexEntry>;
+ /** The extension's docName safety predicate (path-traversal refusal). */
+ isSafeDocName: (docName: string) => boolean;
+ readPageTitleForDocName: (docName: string) => string;
+ readPageTitleForLinkedDocName: (docName: string, admitted: Set<string>) => string;
+ readFrontmatterMetadataForLinkedDocName: (
+ docName: string,
+ admitted: Set<string>,
+ ) => FrontmatterMetadata;
+ collectAdmittedDocNames: () => Promise<Set<string>>;
+ resolveAlias: (docName: string) => string;
+ respondToDerivedIndexQueryFailure: (
+ res: ServerResponse,
+ err: unknown,
+ options: { handler: string; failureTitle: string },
+ ) => void;
+}
+
+export interface LinkGraphRoutes {
+ /** Hono patterns for the native mount (`NativeApiHandle.paths`). */
+ paths: readonly string[];
+ /** The group's view for the shared /api/* admission pipeline. */
+ table: ApiRouteTable;
+}
+
+export function createLinkGraphRoutes(deps: LinkGraphRouteDeps): LinkGraphRoutes {
+ const {
+ hocuspocus,
+ derivedDocumentIndex,
+ getFileIndex,
+ isSafeDocName,
+ readPageTitleForDocName,
+ readPageTitleForLinkedDocName,
+ readFrontmatterMetadataForLinkedDocName,
+ collectAdmittedDocNames,
+ resolveAlias,
+ respondToDerivedIndexQueryFailure,
+ } = deps;
+
+ const handleBacklinks = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ if (!derivedDocumentIndex) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:backlink-index-not-configured',
+ 'Backlink index is not configured.',
+ { handler: 'backlinks' },
+ );
+ return;
+ }
+ try {
+ const url = new URL(req.url ?? '', 'http://localhost');
+ const docName = url.searchParams.get('docName');
+ if (!docName) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {
+ handler: 'backlinks',
+ });
+ return;
+ }
+ if (!isSafeDocName(docName)) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
+ handler: 'backlinks',
+ });
+ return;
+ }
+ const backlinks = (await derivedDocumentIndex.getBacklinks(docName)).map((entry) => ({
+ source: entry.source,
+ anchor: entry.anchor,
+ title: readPageTitleForDocName(entry.source),
+ snippet: entry.snippet,
+ }));
+ successResponse(
+ res,
+ 200,
+ BacklinksSuccessSchema,
+ { docName, backlinks },
+ { handler: 'backlinks' },
+ );
+ } catch (e) {
+ respondToDerivedIndexQueryFailure(res, e, {
+ handler: 'backlinks',
+ failureTitle: 'Failed to read backlinks.',
+ });
+ }
+ },
+ { handler: 'backlinks', method: 'GET', skipBodyParse: true },
+ );
+
+ /**
+ * Bulk backlink-count lookup. `GET /api/backlink-counts?docNames=a,b,c`
+ * returns `{ counts: { a: 3, b: 0, c: 2 } }`. Serves listing UIs
+ * (exec ls/grep/find slim enrichment) that need connection density per file
+ * without N-amplifying the single-doc `/api/backlinks` endpoint.
+ * docNames failing `isSafeDocName` are silently dropped from `counts`.
+ */
+ const handleBacklinkCounts = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ if (!derivedDocumentIndex) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:backlink-index-not-configured',
+ 'Backlink index is not configured.',
+ { handler: 'backlink-counts' },
+ );
+ return;
+ }
+ try {
+ const url = new URL(req.url ?? '', 'http://localhost');
+ const raw = url.searchParams.get('docNames');
+ if (!raw) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docNames parameter.', {
+ handler: 'backlink-counts',
+ });
+ return;
+ }
+ const docNames = raw
+ .split(',')
+ .map((docName) => docName.trim())
+ .filter((docName) => docName && isSafeDocName(docName));
+ const counts = await derivedDocumentIndex.getBacklinkCounts(docNames);
+ successResponse(
+ res,
+ 200,
+ BacklinkCountsSuccessSchema,
+ { counts },
+ { handler: 'backlink-counts' },
+ );
+ } catch (e) {
+ respondToDerivedIndexQueryFailure(res, e, {
+ handler: 'backlink-counts',
+ failureTitle: 'Failed to read backlink counts.',
+ });
+ }
+ },
+ { handler: 'backlink-counts', method: 'GET', skipBodyParse: true },
+ );
+
+ const handleForwardLinks = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ if (!derivedDocumentIndex) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:backlink-index-not-configured',
+ 'Backlink index is not configured.',
+ { handler: 'forward-links' },
+ );
+ return;
+ }
+ try {
+ const url = new URL(req.url ?? '', 'http://localhost');
+ const docName = url.searchParams.get('docName');
+ if (!docName) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {
+ handler: 'forward-links',
+ });
+ return;
+ }
+ if (!isSafeDocName(docName)) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
+ handler: 'forward-links',
+ });
+ return;
+ }
+ const admitted = await collectAdmittedDocNames();
+ successResponse(
+ res,
+ 200,
+ ForwardLinksSuccessSchema,
+ {
+ docName,
+ forwardLinks: (await derivedDocumentIndex.getForwardLinkEntries(docName)).map(
+ (entry) =>
+ entry.kind === 'doc'
+ ? {
+ kind: 'doc' as const,
+ docName: entry.target,
+ anchor: entry.anchor,
+ title: readPageTitleForLinkedDocName(entry.target, admitted),
+ snippet: entry.snippet,
+ }
+ : {
+ kind: 'external' as const,
+ url: entry.url,
+ title: entry.label ?? entry.url,
+ snippet: entry.snippet,
+ },
+ ),
+ },
+ { handler: 'forward-links' },
+ );
+ } catch (e) {
+ respondToDerivedIndexQueryFailure(res, e, {
+ handler: 'forward-links',
+ failureTitle: 'Failed to read forward links.',
+ });
+ }
+ },
+ { handler: 'forward-links', method: 'GET', skipBodyParse: true },
+ );
+
+ const handleLinkGraph = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ if (!derivedDocumentIndex) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:backlink-index-not-configured',
+ 'Backlink index is not configured.',
+ { handler: 'link-graph' },
+ );
+ return;
+ }
+ try {
+ const url = new URL(req.url ?? '', 'http://localhost');
+ const docName = url.searchParams.get('docName');
+ if (docName && !isSafeDocName(docName)) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
+ handler: 'link-graph',
+ });
+ return;
+ }
+
+ const rawDegrees = url.searchParams.get('degrees');
+ if (rawDegrees && !docName) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'docName is required when degrees is provided.',
+ { handler: 'link-graph' },
+ );
+ return;
+ }
+
+ let nodes: DerivedGraphNode[];
+ let links: Array<{ source: string; target: string }>;
+
+ if (rawDegrees && docName) {
+ const degrees = Number.parseInt(rawDegrees, 10);
+ if (!Number.isFinite(degrees) || degrees < 0) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'degrees must be a non-negative integer.',
+ { handler: 'link-graph' },
+ );
+ return;
+ }
+
+ ({ nodes, links } = await derivedDocumentIndex.getLinkGraphNeighborhood(
+ docName,
+ degrees,
+ ));
+ } else {
+ ({ nodes, links } = await derivedDocumentIndex.getLinkGraph());
+ }
+
+ const admitted = await collectAdmittedDocNames();
+ const enrichedNodes = nodes.map((node) => {
+ if (node.kind === 'doc') {
+ const meta = readFrontmatterMetadataForLinkedDocName(node.docName, admitted);
+ return {
+ id: node.id,
+ kind: 'doc' as const,
+ docName: node.docName,
+ anchor: node.anchor ?? null,
+ label: readPageTitleForLinkedDocName(node.docName, admitted),
+ cluster: meta.cluster ?? null,
+ category: meta.category ?? null,
+ tags: meta.tags ?? null,
+ };
+ }
+ return {
+ id: node.id,
+ kind: 'external' as const,
+ url: node.url,
+ label: node.label ?? node.url,
+ };
+ });
+ successResponse(
+ res,
+ 200,
+ LinkGraphSuccessSchema,
+ { nodes: enrichedNodes, links },
+ { handler: 'link-graph' },
+ );
+ } catch (e) {
+ respondToDerivedIndexQueryFailure(res, e, {
+ handler: 'link-graph',
+ failureTitle: 'Failed to read link graph.',
+ });
+ }
+ },
+ { handler: 'link-graph', method: 'GET', skipBodyParse: true },
+ );
+
+ const handleDeadLinks = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ if (!derivedDocumentIndex) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:backlink-index-not-configured',
+ 'Backlink index is not configured.',
+ { handler: 'dead-links' },
+ );
+ return;
+ }
+ try {
+ const url = new URL(req.url ?? '', 'http://localhost');
+ const sourceDocNames = url.searchParams.getAll('sourceDocName');
+ if (sourceDocNames.some((docName) => docName.length === 0 || !isSafeDocName(docName))) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid sourceDocName.', {
+ handler: 'dead-links',
+ });
+ return;
+ }
+
+ const sourceDocNameFilter = sourceDocNames.length
+ ? [...new Set(sourceDocNames.map((docName) => resolveAlias(docName)))]
+ : undefined;
+ const deadLinks = await derivedDocumentIndex.getDeadLinks(
+ await collectAdmittedDocNames(),
+ sourceDocNameFilter,
+ );
+
+ successResponse(
+ res,
+ 200,
+ DeadLinksSuccessSchema,
+ {
+ deadLinks: deadLinks.map((entry) => ({
+ target: entry.target,
+ sources: entry.sources.map((sourceEntry) => ({
+ source: sourceEntry.source,
+ title: readPageTitleForDocName(sourceEntry.source),
+ snippet: sourceEntry.snippet,
+ })),
+ })),
+ },
+ { handler: 'dead-links' },
+ );
+ } catch (e) {
+ respondToDerivedIndexQueryFailure(res, e, {
+ handler: 'dead-links',
+ failureTitle: 'Failed to read dead links.',
+ });
+ }
+ },
+ { handler: 'dead-links', method: 'GET', skipBodyParse: true },
+ );
+
+ const handleSuggestLinks = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ try {
+ const url = new URL(req.url ?? '', 'http://localhost');
+ const docName = url.searchParams.get('docName');
+ if (!docName) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {
+ handler: 'suggest-links',
+ });
+ return;
+ }
+ if (!isSafeDocName(docName)) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
+ handler: 'suggest-links',
+ });
+ return;
+ }
+ if (isSystemDoc(docName) || isConfigDoc(docName)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ `'${docName}' is a reserved document name.`,
+ { handler: 'suggest-links' },
+ );
+ return;
+ }
+
+ const result = await suggestLinks({
+ hocuspocus,
+ fileIndex: getFileIndex(),
+ docName,
+ });
+ successResponse(res, 200, SuggestLinksSuccessSchema, result, { handler: 'suggest-links' });
+ } catch (error) {
+ if (error instanceof SuggestLinksTargetNotFoundError) {
+ errorResponse(res, 404, 'urn:ok:error:doc-not-found', 'Page not found.', {
+ handler: 'suggest-links',
+ cause: error,
+ });
+ return;
+ }
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to suggest links.', {
+ handler: 'suggest-links',
+ cause: error,
+ });
+ }
+ },
+ { handler: 'suggest-links', method: 'GET', skipBodyParse: true },
+ );
+
+ const handleTagsList = withValidation(
+ EmptyRequestSchema,
+ async (_req, res) => {
+ if (!derivedDocumentIndex) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:tag-index-not-configured',
+ 'Tag index not configured.',
+ { handler: 'tags-list' },
+ );
+ return;
+ }
+ try {
+ const tags = await derivedDocumentIndex.getAllTags();
+ successResponse(res, 200, TagsListSuccessSchema, { tags }, { handler: 'tags-list' });
+ } catch (e) {
+ respondToDerivedIndexQueryFailure(res, e, {
+ handler: 'tags-list',
+ failureTitle: 'Failed to read tags.',
+ });
+ }
+ },
+ { handler: 'tags-list', method: 'GET', skipBodyParse: true },
+ );
+
+ async function handleTagsForName(
+ req: IncomingMessage,
+ res: ServerResponse,
+ rawName: string,
+ ): Promise<void> {
+ if (req.method !== 'GET') {
+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
+ handler: 'tags-for-name',
+ extraHeaders: { Allow: 'GET' },
+ });
+ return;
+ }
+ if (!derivedDocumentIndex) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:tag-index-not-configured',
+ 'Tag index not configured.',
+ { handler: 'tags-for-name' },
+ );
+ return;
+ }
+ let name: string;
+ try {
+ name = decodeURIComponent(rawName);
+ } catch (uriErr) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid tag name encoding.', {
+ handler: 'tags-for-name',
+ cause: uriErr,
+ });
+ return;
+ }
+ if (!name) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing tag name.', {
+ handler: 'tags-for-name',
+ });
+ return;
+ }
+ try {
+ const docs = (await derivedDocumentIndex.getDocsForTagWithMatches(name)).map(
+ ({ docName, matchingTags }) => ({
+ docName,
+ title: readPageTitleForDocName(docName),
+ matchingTags,
+ snippet: null,
+ }),
+ );
+ successResponse(
+ res,
+ 200,
+ TagsForNameSuccessSchema,
+ { name, docs },
+ {
+ handler: 'tags-for-name',
+ },
+ );
+ } catch (e) {
+ respondToDerivedIndexQueryFailure(res, e, {
+ handler: 'tags-for-name',
+ failureTitle: 'Failed to read tag membership.',
+ });
+ }
+ }
+
+ const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {
+ '/api/backlinks': handleBacklinks,
+ '/api/backlink-counts': handleBacklinkCounts,
+ '/api/forward-links': handleForwardLinks,
+ '/api/link-graph': handleLinkGraph,
+ '/api/dead-links': handleDeadLinks,
+ '/api/tags': handleTagsList,
+ '/api/suggest-links': handleSuggestLinks,
+ };
+
+ const table: ApiRouteTable = {
+ resolve(url) {
+ const handler = routes[url];
+ if (handler) {
+ return { template: url, dispatch: (req, res) => handler(req, res) };
+ }
+ if (url.startsWith('/api/tags/')) {
+ const rawName = url.slice('/api/tags/'.length);
+ return {
+ template: '/api/tags/:name',
+ // Empty name (`/api/tags/`): no dispatch — the pipeline's explicit
+ // 404 owns it, under the same template the legacy dispatch used.
+ dispatch: rawName ? (req, res) => handleTagsForName(req, res, rawName) : undefined,
+ };
+ }
+ return null;
+ },
+ // Every route in this group is a read (none rode the legacy
+ // MUTATING_ROUTES loopback/Host gate).
+ isMutating: () => false,
+ };
+
+ return {
+ // `/api/tags/*` (not `:name`) so an empty or slash-containing tail
+ // reaches the table exactly like the legacy prefix match did.
+ paths: [...Object.keys(routes), '/api/tags/*'],
+ table,
+ };
+}
diff --git a/packages/server/src/mcp-mount.test.ts b/packages/server/src/mcp-mount.test.ts
index f2a78a841..86cb83aa6 100644
--- a/packages/server/src/mcp-mount.test.ts
+++ b/packages/server/src/mcp-mount.test.ts
@@ -46,6 +46,7 @@ async function startMountedServer(
const httpServer = createServer();
const mount = mountMcpAndApi({
httpServer,
+ nativeApi: undefined,
hocuspocus: serverHocuspocus,
mcpHttpHandler: handler,
log,
@@ -332,7 +333,7 @@ describe('mountMcpAndApi shutdown drains live WS clients', () => {
for (const path of ['/collab', '/collab/keepalive?connectionId=teardown-probe']) {
test(`drains live ${path.split('?')[0]} WS so wss.close + httpServer.close resolve promptly`, async () => {
const httpServer = createServer();
- const mount = mountMcpAndApi({ httpServer, hocuspocus, log });
+ const mount = mountMcpAndApi({ httpServer, nativeApi: undefined, hocuspocus, log });
const port = await getFreeLoopbackPort();
await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
@@ -405,6 +406,7 @@ describe('mountMcpAndApi content-asset middleware', () => {
};
const mount = mountMcpAndApi({
httpServer,
+ nativeApi: undefined,
hocuspocus,
log,
contentAssetMiddleware: createAssetServeMiddleware({
@@ -477,6 +479,7 @@ describe('mountMcpAndApi content-asset middleware', () => {
const httpServer = createServer();
const mount = mountMcpAndApi({
httpServer,
+ nativeApi: undefined,
hocuspocus,
log,
contentAssetMiddleware: () => {
@@ -521,6 +524,7 @@ describe('mountMcpAndApi ephemeral content-asset gate', () => {
const httpServer = createServer();
const mount = mountMcpAndApi({
httpServer,
+ nativeApi: undefined,
hocuspocus,
log,
ephemeral,
@@ -599,6 +603,7 @@ describe('mountMcpAndApi react-shell middleware', () => {
const httpServer = createServer();
const mount = mountMcpAndApi({
httpServer,
+ nativeApi: undefined,
hocuspocus,
log,
contentAssetMiddleware: opts?.contentAssetMiddleware,
diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.ts
index 4cfbf923b..d4d8c4ee7 100644
--- a/packages/server/src/mcp-mount.ts
+++ b/packages/server/src/mcp-mount.ts
@@ -31,16 +31,17 @@ import type { AgentSessionManager } from './agent-sessions.ts';
import { isAllowedApiOrigin } from './api-origin.ts';
import { createCollaborationHost } from './collaboration-host.ts';
import { errorResponse } from './http/error-response.ts';
-import { createHttpApp, type HealthProvider } from './http/http-app.ts';
+import {
+ admitRequestSurface,
+ createHttpApp,
+ type HealthProvider,
+ type NativeApiHandle,
+} from './http/http-app.ts';
import type { PinoLogger } from './logger.ts';
import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';
import type { MaintenanceCoordinator } from './maintenance-coordinator.ts';
import type { McpHttpHandler } from './mcp-http.ts';
-import {
- hasForwardingHeaders,
- isRemoteAdmitted,
- type ResolvedRemoteAccess,
-} from './remote-access.ts';
+import { hasForwardingHeaders, type ResolvedRemoteAccess } from './remote-access.ts';
export type { ReadinessState } from './http/http-app.ts';
@@ -139,6 +140,16 @@ export interface MountMcpAndApiOptions {
* health routes still mount and report ready with no degraded subsystems.
*/
health?: HealthProvider;
+ /**
+ * Natively-served `/api/*` route groups (the `ServerInstance.nativeApi`
+ * handle). When supplied, the Hono app claims these paths ahead of the
+ * strangler catch-all and runs them through the shared admission pipeline.
+ * Required-but-undefinable rather than optional: forgetting the wiring at
+ * a mount site would silently 404 every ported route out of the legacy
+ * dispatch, so passing `undefined` (harnesses that never touch ported
+ * routes) must be an explicit decision, not an omission.
+ */
+ nativeApi: NativeApiHandle | undefined;
/**
* Resolved `remote:` config (null/undefined ⇒ remote access disabled).
* When set, EVERY surface (`/mcp`, `/api/*`, `/collab`, content assets,
@@ -215,30 +226,11 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
const onRequest = (req: IncomingMessage, res: ServerResponse): void => {
const url = req.url?.split('?')[0];
- // Tripwire: proxy-forwarding headers on a server that never opted into
- // remote access mean a tunnel is pointed at us. Refuse with the fix
- // instruction — the alternative is silently serving a public tunnel with
- // full local trust, decided by whether the tunnel rewrites Host.
- if (remoteAccess === undefined && hasForwardingHeaders(req)) {
- errorResponse(
- res,
- 403,
- 'urn:ok:error:host-not-allowed',
- 'Proxied request refused: this server was not started for remote access. Restart with `ok start --remote` to serve through a tunnel.',
- { handler: 'mcp-mount' },
- );
- return;
- }
- // With remote access enabled, ONE admit decision covers every surface
- // (trust-the-tunnel — see remote-access.ts): loopback socket + Host on
- // the allowlist (loopback names or the tunnel's public host). Refusals
- // are wrong-Host callers (DNS-rebound pages), not auth failures.
- if (remoteAccess !== undefined && !isRemoteAdmitted(req, remoteAccess)) {
- errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
- handler: 'mcp-mount',
- });
- return;
- }
+ // Surface-wide admission prelude — the proxied-request tripwire plus the
+ // remote-access admit decision. Shared with the natively-mounted /api/*
+ // routes (`admitRequestSurface` in http-app.ts), which sit above the
+ // strangler catch-all and would otherwise bypass it.
+ if (!admitRequestSurface(req, res, remoteAccess, 'mcp-mount')) return;
if (mcpHttpHandler !== undefined && url === '/mcp') {
const origin = req.headers.origin;
const sessionId = Array.isArray(req.headers['mcp-session-id'])
@@ -445,12 +437,14 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
socket.destroy();
};
- // The canonical Hono app owns top-level routing (health natively; every
- // unmigrated surface falls through its catch-all into `onRequest`
- // unchanged). The WS upgrade path stays a raw listener — it never routes
- // through HTTP dispatch.
+ // The canonical Hono app owns top-level routing (health + ported /api/*
+ // groups natively; every unmigrated surface falls through its catch-all
+ // into `onRequest` unchanged). The WS upgrade path stays a raw listener —
+ // it never routes through HTTP dispatch.
const { requestListener } = createHttpApp({
health: opts.health,
+ nativeApi: opts.nativeApi,
+ remoteAccess,
legacyDispatch: onRequest,
log,
});
diff --git a/packages/server/src/remote-mcp.test.ts b/packages/server/src/remote-mcp.test.ts
index 48eded014..85e380039 100644
--- a/packages/server/src/remote-mcp.test.ts
+++ b/packages/server/src/remote-mcp.test.ts
@@ -101,6 +101,7 @@ async function bootRemoteRig(
const httpServer: HttpServer = createHttpServer();
const mount: MountMcpAndApiHandle = mountMcpAndApi({
httpServer,
+ nativeApi: undefined,
hocuspocus,
mcpHttpHandler: handler,
remoteAccess,
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index 8ea18aa26..788943053 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -132,6 +132,7 @@ import type {
} from './github-permissions.ts';
import { type HeadWatcherHandle, readProjectHeadState, startHeadWatcher } from './head-watcher.ts';
import { errnoCode } from './http/handler-utils.ts';
+import type { NativeApiHandle } from './http/http-app.ts';
import { scanGlobalInPlaceSkills, scanInPlaceSkillDirs } from './in-place-skills.ts';
import { createLiveDerivedIndexExtension } from './live-derived-index.ts';
import { getLogger } from './logger.ts';
@@ -401,6 +402,13 @@ export interface ServerOptions {
export interface ServerInstance {
hocuspocus: Hocuspocus;
sessionManager: AgentSessionManager;
+ /**
+ * Natively-routed /api/* groups (paths + the shared admission pipeline
+ * bound to their table). Callers that mount HTTP dispatch — `bootServer`
+ * via `mountMcpAndApi`, the Vite dev plugin, the integration harness —
+ * MUST wire this in, or the ported routes 404 out of the legacy dispatch.
+ */
+ nativeApi: NativeApiHandle;
cc1Broadcaster: CC1Broadcaster;
agentFocusBroadcaster: AgentFocusBroadcaster;
agentPresenceBroadcaster: AgentPresenceBroadcaster;
@@ -1047,6 +1055,10 @@ export function createServer(options: ServerOptions): ServerInstance {
let lossRing: LossCaptureRing | undefined;
let hocuspocus: Hocuspocus;
let sessionManager: AgentSessionManager;
+ // Natively-routed /api/* groups exposed by the api extension; handed to
+ // `mountMcpAndApi` (and the Vite dev plugin) so the Hono app can claim the
+ // ported paths ahead of the strangler catch-all.
+ let nativeApi: NativeApiHandle;
// Set at boot when the loss detector is enabled; shared by the agent-session
// manager (agent-undo) and the file-watcher intake path (dirty-open-doc).
let bridgeLossReporter: BridgeDeriveLossReporter | undefined;
@@ -1940,6 +1952,7 @@ export function createServer(options: ServerOptions): ServerInstance {
},
});
hocuspocus.configuration.extensions.push(apiExtension);
+ nativeApi = apiExtension.nativeApi;
// Bridge loss-hardening wiring: resolve the defer-guard kill-switch
// and construct the content-free loss ring once at boot. Reading the
@@ -4558,6 +4571,7 @@ export function createServer(options: ServerOptions): ServerInstance {
hocuspocus,
durabilityState,
sessionManager,
+ nativeApi,
cc1Broadcaster,
agentFocusBroadcaster,
agentPresenceBroadcaster,