Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Refuse opaque-origin writes and non-JSON bodies on the local /api (#5342)
Andrew Mikofalvy8dac4b194ac1
diff --git a/.changeset/api-opaque-origin-guard.md b/.changeset/api-opaque-origin-guard.mdnew file mode 100644index 000000000..88be898af--- /dev/null+++ b/.changeset/api-opaque-origin-guard.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Sandboxed iframes can no longer read the local OpenKnowledge server's API, change documents, or open collaboration or agent connections. API write requests that send JSON must now label it as JSON.diff --git a/packages/app/tests/integration/api-error-envelope/agent-integrations-apply.test.ts b/packages/app/tests/integration/api-error-envelope/agent-integrations-apply.test.tsindex b911fe52e..4e22ffb83 100644--- a/packages/app/tests/integration/api-error-envelope/agent-integrations-apply.test.ts+++ b/packages/app/tests/integration/api-error-envelope/agent-integrations-apply.test.ts@@ -32,10 +32,38 @@ afterAll(async () => {});describe('agent-integrations apply — a host with no writers injected', () => {- test('accepts loose JSON without a Content-Type gate and emits shared success headers', async () => {+ test('refuses a JSON body that is not labeled JSON, the shapes a cross-site form, beacon or curl -d sends', async () => {+ const json = JSON.stringify({+ intents: [{ satisfierId: CLAUDE_PROJECT_MCP, desired: 'present' }],+ });+ const cases: Array<[string, RequestInit]> = [+ ['no Content-Type at all', { body: new TextEncoder().encode(json) }],+ ['text/plain', { headers: { 'Content-Type': 'text/plain;charset=UTF-8' }, body: json }],+ [+ 'form-urlencoded',+ { headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: json },+ ],+ ];+ for (const [label, init] of cases) {+ const res = await fetch(`${base()}/api/agent-integrations/apply`, {+ method: 'POST',+ ...init,+ });+ expect(res.status, label).toBe(415);+ const problem = ProblemDetailsSchema.parse(await res.json());+ expect(problem.type, label).toBe('urn:ok:error:unsupported-media-type');+ expect(problem.detail, label).toContain('Content-Type: application/json');+ }+ });++ test('accepts loose JSON fields and emits shared success headers', async () => {const res = await fetch(`${base()}/api/agent-integrations/apply`, {method: 'POST',- headers: { Origin: 'http://localhost:5173', 'X-Request-Id': 'apply-success-contract' },+ headers: {+ 'Content-Type': 'application/json',+ Origin: 'http://localhost:5173',+ 'X-Request-Id': 'apply-success-contract',+ },body: JSON.stringify({intents: [{ satisfierId: CLAUDE_PROJECT_MCP, desired: 'present', futureIntentField: true }],futureRequestField: true,@@ -105,6 +133,7 @@ describe('agent-integrations apply — a host with no writers injected', () => {test('matches the exact path with a query but not a slash or neighboring path', async () => {const query = await fetch(`${base()}/api/agent-integrations/apply?source=test`, {method: 'POST',+ headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ intents: [] }),});expect(query.status).toBe(200);@@ -173,7 +202,7 @@ describe('agent-integrations apply — refusals use the shared envelope', () =>])('rejects %s with its validation title', async (_label, body, title) => {const res = await fetch(`${base()}/api/agent-integrations/apply`, {method: 'POST',- ...(body === undefined ? {} : { body }),+ ...(body === undefined ? {} : { headers: { 'Content-Type': 'application/json' }, body }),});expect(res.status).toBe(400);const problem = ProblemDetailsSchema.parse(await res.json());@@ -208,6 +237,7 @@ describe('agent-integrations apply — refusals use the shared envelope', () =>test('rejects a body larger than one mebibyte', async () => {const res = await fetch(`${base()}/api/agent-integrations/apply`, {method: 'POST',+ headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ intents: [], extra: 'x'.repeat(1_048_576) }),});expect(res.status).toBe(413);@@ -288,6 +318,7 @@ describe('agent-integrations apply — refusals use the shared envelope', () =>{method: 'POST',headers: {+ 'Content-Type': 'application/json',Origin: 'https://integrations.example.com','X-Forwarded-For': '203.0.113.8',},@@ -320,6 +351,7 @@ describe('agent-integrations apply — ephemeral admission', () => {});const res = await fetch(`http://127.0.0.1:${ephemeral.port}/api/agent-integrations/apply`, {method: 'POST',+ headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ intents: [] }),});expect(res.status).toBe(200);diff --git a/packages/app/tests/integration/origin-undoability-sweep.uncached.test.ts b/packages/app/tests/integration/origin-undoability-sweep.uncached.test.tsindex 236a2f60f..11de8d964 100644--- a/packages/app/tests/integration/origin-undoability-sweep.uncached.test.ts+++ b/packages/app/tests/integration/origin-undoability-sweep.uncached.test.ts@@ -134,6 +134,8 @@ const NON_CONTENT_ORIGINS: Record<string, string> = {'The uninstall-feedback submission source label, not a CRDT transaction origin.',LAUNCHER_FREE_ORIGIN:'The default provenance stamp on a menu-action dispatch, describing whether the surface that dispatched dismisses itself. It rides the menu-action bus, never a Y.Doc transaction.',+ OPAQUE_ORIGIN_REFUSAL_DETAIL:+ 'The problem-details text the server sends when it refuses a null or file: HTTP Origin header, never a Y.Doc transaction origin.',};const HERE = import.meta.dirname;diff --git a/packages/core/src/handoff/urn-ipc-registry.ts b/packages/core/src/handoff/urn-ipc-registry.tsindex 19ca39b46..aff3c3c62 100644--- a/packages/core/src/handoff/urn-ipc-registry.ts+++ b/packages/core/src/handoff/urn-ipc-registry.ts@@ -34,6 +34,7 @@ export const URN_HTTP_ONLY: ReadonlySet<ProblemType> = new Set<ProblemType>(['urn:ok:error:storage-error','urn:ok:error:no-file-received','urn:ok:error:method-not-allowed',+ 'urn:ok:error:unsupported-media-type','urn:ok:error:payload-too-large','urn:ok:error:request-timeout','urn:ok:error:internal-server-error',diff --git a/packages/core/src/schemas/api/_envelope.ts b/packages/core/src/schemas/api/_envelope.tsindex 16a7c2839..c3ffd559d 100644--- a/packages/core/src/schemas/api/_envelope.ts+++ b/packages/core/src/schemas/api/_envelope.ts@@ -57,6 +57,7 @@ export const ProblemTypeSchema = z.enum(['urn:ok:error:symlink-refused','urn:ok:error:method-not-allowed','urn:ok:error:invalid-request',+ 'urn:ok:error:unsupported-media-type','urn:ok:error:payload-too-large','urn:ok:error:request-timeout','urn:ok:error:internal-server-error',diff --git a/packages/desktop/scripts/afterSign.mjs b/packages/desktop/scripts/afterSign.mjsindex 549e821a1..bdf39a479 100644--- a/packages/desktop/scripts/afterSign.mjs+++ b/packages/desktop/scripts/afterSign.mjs@@ -139,7 +139,9 @@ async function verifyFuses(electronBinary, expected) {`[afterSign] fuse verification failed (D17 paranoid check):\n ${mismatches.join('\n ')}`,);}- console.log('[afterSign] fuse verification passed — all 6 fuses match targetFuses');+ console.log(+ `[afterSign] fuse verification passed: all ${Object.keys(expected).length} fuses match targetFuses`,+ );}export default async function afterSign(context) {diff --git a/packages/desktop/scripts/target-fuses.mjs b/packages/desktop/scripts/target-fuses.mjsindex 6a4578fdc..58fe00fb3 100644--- a/packages/desktop/scripts/target-fuses.mjs+++ b/packages/desktop/scripts/target-fuses.mjs@@ -8,6 +8,7 @@ export const targetFuses = {[FuseV1Options.EnableNodeCliInspectArguments]: true,[FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,[FuseV1Options.OnlyLoadAppFromAsar]: true,+ [FuseV1Options.GrantFileProtocolExtraPrivileges]: true,};export function fuseStateName(state) {diff --git a/packages/desktop/tests/unit/target-fuses.test.mjs b/packages/desktop/tests/unit/target-fuses.test.mjsnew file mode 100644index 000000000..604cbab80--- /dev/null+++ b/packages/desktop/tests/unit/target-fuses.test.mjs@@ -0,0 +1,12 @@+import { FuseState, FuseV1Options } from '@electron/fuses';+import { describe, expect, test } from 'vitest';+import { expectedFuseState, targetFuses } from '../../scripts/target-fuses.mjs';++describe('packaged fuse targets', () => {+ test('keep file protocol privileges on, so the packaged renderer reaches the local API without an opaque Origin', () => {+ expect(targetFuses[FuseV1Options.GrantFileProtocolExtraPrivileges]).toBe(true);+ expect(expectedFuseState(targetFuses[FuseV1Options.GrantFileProtocolExtraPrivileges])).toBe(+ FuseState.ENABLE,+ );+ });+});diff --git a/packages/server/src/api-agent-write-native-preservation.test.ts b/packages/server/src/api-agent-write-native-preservation.test.tsindex c7f886329..cfecc2d1f 100644--- a/packages/server/src/api-agent-write-native-preservation.test.ts+++ b/packages/server/src/api-agent-write-native-preservation.test.ts@@ -161,7 +161,8 @@ test('disabled test routes retain unknown-path admission, in ephemeral servers',}for (const path of WRITES) {const response = await rawRequest(ephemeral.port, path, { method: 'POST', body: '{' });- expect(response.status, `${path}: ${response.body}`).toBe(400);+ expect(response.status, `${path}: ${response.body}`).toBe(415);+ expect(parseProblem(response.body).type, path).toBe('urn:ok:error:unsupported-media-type');}for (const path of READS) {const response = await rawRequest(ephemeral.port, path);diff --git a/packages/server/src/api-link-preview.test.ts b/packages/server/src/api-link-preview.test.tsindex a40bf5515..3f4052af8 100644--- a/packages/server/src/api-link-preview.test.ts+++ b/packages/server/src/api-link-preview.test.ts@@ -175,7 +175,7 @@ describe('POST /api/link-preview anti-proxy gate', () => {expect(fake.calls).toHaveLength(0);});- test('rejects a non-JSON content type without fetching', async () => {+ test('rejects a non-JSON content type with the shared 415 without fetching', async () => {const fake = makeFakeFetch({ html: '<title>never</title>' });const harness = await rig.open(fake.impl);const res = await postPreview(harness.baseURL, {@@ -183,7 +183,10 @@ describe('POST /api/link-preview anti-proxy gate', () => {contentType: 'text/plain',body: JSON.stringify({ url: 'https://example.com' }),});- expect(res.status).toBe(400);+ expect(res.status).toBe(415);+ expect(((await res.json()) as { type?: string }).type).toBe(+ 'urn:ok:error:unsupported-media-type',+ );expect(fake.calls).toHaveLength(0);});diff --git a/packages/server/src/api-opaque-origin-composition.test.ts b/packages/server/src/api-opaque-origin-composition.test.tsnew file mode 100644index 000000000..43a92a2f7--- /dev/null+++ b/packages/server/src/api-opaque-origin-composition.test.ts@@ -0,0 +1,337 @@+import { existsSync, mkdtempSync, readdirSync, 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 { WebSocket as WsClient } from 'ws';+import type { BootedServer } from './boot.ts';+import {+ bootCompositionRig,+ parseProblem,+ type RawResponse,+ rawRequest,+} from './composition-rig.test-helper.ts';+import { OPAQUE_ORIGIN_REFUSAL_DETAIL } from './ingress-policy.ts';++const LOOPBACK_ORIGIN = 'http://localhost:5173';+const MCP_INITIALIZE = JSON.stringify({+ jsonrpc: '2.0',+ id: 1,+ method: 'initialize',+ params: {+ protocolVersion: '2025-06-18',+ capabilities: {},+ clientInfo: { name: 'opaque-origin-composition', version: '0.0.0' },+ },+});++let tmpRoot: string;+let contentDir: string;+let server: BootedServer;++function contentFiles(): string[] {+ return readdirSync(contentDir, { recursive: true, encoding: 'utf-8' })+ .filter((entry) => !entry.startsWith('.ok') && !entry.startsWith('.git'))+ .sort();+}++function expectNoCorsGrant(res: RawResponse | Response): void {+ const header = (name: string) =>+ res instanceof Response ? res.headers.get(name) : (res.headers[name] ?? null);+ expect(header('access-control-allow-origin')).toBeNull();+ expect(header('access-control-allow-methods')).toBeNull();+ expect(header('access-control-allow-headers')).toBeNull();+}++function uploadForm(name: string): FormData {+ const form = new FormData();+ form.append('parentDocName', 'alpha');+ form.append('file', new Blob([`png-ish bytes for ${name}`]), name);+ return form;+}++function upgradeOutcome(path: string, origin: string | undefined): Promise<'open' | 'refused'> {+ return new Promise((resolvePromise, reject) => {+ const ws = new WsClient(+ `ws://127.0.0.1:${server.port}${path}`,+ origin === undefined ? {} : { origin },+ );+ const timer = setTimeout(() => {+ ws.terminate();+ reject(new Error(`timed out waiting for the ${path} upgrade outcome`));+ }, 5_000);+ const settle = (outcome: 'open' | 'refused') => {+ clearTimeout(timer);+ ws.terminate();+ resolvePromise(outcome);+ };+ ws.once('open', () => settle('open'));+ ws.once('unexpected-response', () => settle('refused'));+ ws.once('error', () => settle('refused'));+ });+}++beforeAll(async () => {+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-opaque-origin-'));+ contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));+ writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nPrivate body.\n', 'utf-8');+ server = await bootCompositionRig(contentDir);+ await server.ready;+}, 60_000);++afterAll(async () => {+ await server?.destroy();+ await rm(tmpRoot, { recursive: true, force: true });+});++describe('reads from an opaque origin on the real server', () => {+ test('GET /api/document from null is refused; from file:// it carries no grant; loopback keeps its grant', async () => {+ const fromNull = await rawRequest(server.port, '/api/document?docName=alpha', {+ headers: { Origin: 'null' },+ });+ expect(fromNull.status).toBe(403);+ expect(parseProblem(fromNull.body)).toMatchObject({+ type: 'urn:ok:error:invalid-origin',+ detail: OPAQUE_ORIGIN_REFUSAL_DETAIL,+ });+ expect(fromNull.body).not.toContain('Private body.');+ expectNoCorsGrant(fromNull);++ const fromFile = await rawRequest(server.port, '/api/document?docName=alpha', {+ headers: { Origin: 'file://' },+ });+ expect(fromFile.status).toBe(200);+ expectNoCorsGrant(fromFile);++ const loopback = await rawRequest(server.port, '/api/document?docName=alpha', {+ headers: { Origin: LOOPBACK_ORIGIN },+ });+ expect(loopback.status).toBe(200);+ expect(loopback.headers['access-control-allow-origin']).toBe(LOOPBACK_ORIGIN);+ expect((JSON.parse(loopback.body) as { content?: string }).content).toContain('Private body.');+ });++ test('the preflight an opaque origin would need is not granted; the loopback preflight is', async () => {+ for (const path of ['/api/document?docName=alpha', '/api/create-page', '/api/upload']) {+ for (const [origin, status] of [+ ['null', 403],+ ['file://', 204],+ ] as const) {+ const res = await rawRequest(server.port, path, {+ method: 'OPTIONS',+ headers: {+ Origin: origin,+ 'Access-Control-Request-Method': 'POST',+ 'Access-Control-Request-Headers': 'content-type',+ },+ });+ expect(res.status, `${origin} ${path}`).toBe(status);+ expectNoCorsGrant(res);+ }+ const loopback = await rawRequest(server.port, path, {+ method: 'OPTIONS',+ headers: { Origin: LOOPBACK_ORIGIN, 'Access-Control-Request-Method': 'POST' },+ });+ expect(loopback.status, path).toBe(204);+ expect(loopback.headers['access-control-allow-origin'], path).toBe(LOOPBACK_ORIGIN);+ }+ });++ test('a GET carrying a stray content-type still reads the document', async () => {+ const res = await rawRequest(server.port, '/api/document?docName=alpha', {+ headers: { 'Content-Type': 'text/plain' },+ });+ expect(res.status).toBe(200);+ expect((JSON.parse(res.body) as { content?: string }).content).toContain('Private body.');+ });+});++describe('writes on the real server take JSON from a site origin only', () => {+ test('POST /api/create-page with a text/plain JSON body answers 415 and creates nothing', async () => {+ const before = contentFiles();+ for (const headers of [+ { 'Content-Type': 'text/plain' },+ { 'Content-Type': 'text/plain', Origin: LOOPBACK_ORIGIN },+ ]) {+ const res = await rawRequest(server.port, '/api/create-page', {+ method: 'POST',+ headers,+ body: JSON.stringify({ path: 'simple-request.md' }),+ });+ expect(res.status).toBe(415);+ expect(res.headers['content-type']).toBe('application/problem+json');+ const problem = parseProblem(res.body);+ expect(problem.type).toBe('urn:ok:error:unsupported-media-type');+ expect(problem.detail).toContain('Content-Type: application/json');+ }+ expect(existsSync(resolve(contentDir, 'simple-request.md'))).toBe(false);+ expect(contentFiles()).toEqual(before);+ });++ test('every JSON write route refuses a text/plain body with 415, direct body readers included', async () => {+ for (const path of [+ '/api/create-page',+ '/api/agent-write',+ '/api/skill/install',+ '/api/comment',+ '/api/comments',+ '/api/handoff',+ '/api/spawn-cursor',+ '/api/link-preview',+ ]) {+ const res = await rawRequest(server.port, path, {+ method: 'POST',+ headers: {+ 'Content-Type': 'text/plain',+ ...(path === '/api/link-preview' ? { Origin: LOOPBACK_ORIGIN } : {}),+ },+ body: 'not json',+ });+ expect(res.status, `${path}: ${res.body}`).toBe(415);+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:unsupported-media-type');+ }+ });++ test('a multipart upload from a site origin lands in the content root, a JSON body there is malformed-upload', async () => {+ const before = contentFiles();+ const ok = await fetch(`http://127.0.0.1:${server.port}/api/upload`, {+ method: 'POST',+ headers: { Origin: LOOPBACK_ORIGIN },+ body: uploadForm('site-upload.png'),+ });+ expect(ok.status).toBe(200);+ const afterUpload = contentFiles();+ expect(afterUpload).toEqual([...before, 'site-upload.png'].sort());++ const json = await rawRequest(server.port, '/api/upload', {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ parentDocName: 'alpha' }),+ });+ expect(json.status).toBe(400);+ expect(parseProblem(json.body).type).toBe('urn:ok:error:malformed-upload');+ expect(contentFiles()).toEqual(afterUpload);+ });++ test('every write from an opaque origin is refused 403 and creates nothing', async () => {+ const before = contentFiles();+ for (const origin of ['null', 'file://']) {+ for (const contentType of ['text/plain', 'application/json']) {+ const res = await rawRequest(server.port, '/api/create-page', {+ method: 'POST',+ headers: { 'Content-Type': contentType, Origin: origin },+ body: JSON.stringify({ path: 'opaque-write.md' }),+ });+ expect(res.status, `${origin} ${contentType}`).toBe(403);+ expect(parseProblem(res.body)).toMatchObject({+ type: 'urn:ok:error:invalid-origin',+ detail: OPAQUE_ORIGIN_REFUSAL_DETAIL,+ });+ expectNoCorsGrant(res);+ }+ const upload = await fetch(`http://127.0.0.1:${server.port}/api/upload`, {+ method: 'POST',+ headers: { Origin: origin },+ body: uploadForm('opaque-upload.png'),+ });+ expect(upload.status, origin).toBe(403);+ expect(((await upload.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-origin');+ expectNoCorsGrant(upload);+ }+ expect(existsSync(resolve(contentDir, 'opaque-write.md'))).toBe(false);+ expect(contentFiles()).toEqual(before);+ });++ test('application/json create-page still works bare and same-origin with the app headers', async () => {+ const bare = await rawRequest(server.port, '/api/create-page', {+ method: 'POST',+ headers: { 'content-type': 'application/json' },+ body: JSON.stringify({ path: 'seeded-bare.md' }),+ });+ expect(bare.status).toBe(200);+ expect(existsSync(resolve(contentDir, 'seeded-bare.md'))).toBe(true);++ const sameOrigin = `http://127.0.0.1:${server.port}`;+ const app = await fetch(`${sameOrigin}/api/create-page`, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ Origin: sameOrigin,+ 'x-ok-client-protocol': '1',+ 'x-ok-client-runtime': '0.0.0-test',+ 'x-ok-client-kind': 'web',+ },+ body: JSON.stringify({ path: 'seeded-app.md' }),+ });+ expect(app.status).toBe(200);+ expect(app.headers.get('access-control-allow-origin')).toBe(sameOrigin);+ expect(existsSync(resolve(contentDir, 'seeded-app.md'))).toBe(true);+ });+});++describe('/mcp on the real server', () => {+ test('MCP from an opaque origin is refused and its preflight is not granted', async () => {+ for (const origin of ['null', 'file://']) {+ const init = await rawRequest(server.port, '/mcp', {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ Accept: 'application/json, text/event-stream',+ Origin: origin,+ },+ body: MCP_INITIALIZE,+ });+ expect(init.status, origin).toBe(403);+ expect(parseProblem(init.body)).toMatchObject({+ type: 'urn:ok:error:invalid-origin',+ detail: OPAQUE_ORIGIN_REFUSAL_DETAIL,+ });+ expectNoCorsGrant(init);++ const preflight = await rawRequest(server.port, '/mcp', {+ method: 'OPTIONS',+ headers: { Origin: origin, 'Access-Control-Request-Method': 'POST' },+ });+ expect(preflight.status, origin).toBe(origin === 'null' ? 403 : 204);+ expectNoCorsGrant(preflight);+ }+ const loopback = await rawRequest(server.port, '/mcp', {+ method: 'OPTIONS',+ headers: { Origin: LOOPBACK_ORIGIN, 'Access-Control-Request-Method': 'POST' },+ });+ expect(loopback.status).toBe(204);+ expect(loopback.headers['access-control-allow-origin']).toBe(LOOPBACK_ORIGIN);+ });++ test('an MCP client without an Origin still initializes', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/mcp`, {+ method: 'POST',+ headers: {+ 'content-type': 'application/json',+ accept: 'application/json, text/event-stream',+ },+ body: MCP_INITIALIZE,+ });+ expect(res.status).toBe(200);+ expect(res.headers.get('mcp-session-id')).toBeTruthy();+ });+});++describe('collaboration WebSocket upgrades on the real server', () => {+ test('/collab refuses a null origin and still opens for the desktop file:// origin and loopback', async () => {+ await expect(upgradeOutcome('/collab', 'null')).resolves.toBe('refused');+ await expect(upgradeOutcome('/collab', 'file://')).resolves.toBe('open');+ await expect(upgradeOutcome('/collab', LOOPBACK_ORIGIN)).resolves.toBe('open');+ });++ test('/collab/thread refuses a null origin and still opens for file:// and loopback', async () => {+ await expect(upgradeOutcome('/collab/thread', 'null')).resolves.toBe('refused');+ await expect(upgradeOutcome('/collab/thread', 'file://')).resolves.toBe('open');+ await expect(upgradeOutcome('/collab/thread', LOOPBACK_ORIGIN)).resolves.toBe('open');+ });++ test('/collab/keepalive refuses a null origin and still opens without one', async () => {+ await expect(upgradeOutcome('/collab/keepalive', 'null')).resolves.toBe('refused');+ await expect(upgradeOutcome('/collab/keepalive', undefined)).resolves.toBe('open');+ });+});diff --git a/packages/server/src/api-origin.test.ts b/packages/server/src/api-origin.test.tsindex 20f4c0741..f87e3e908 100644--- a/packages/server/src/api-origin.test.ts+++ b/packages/server/src/api-origin.test.ts@@ -1,9 +1,9 @@import { describe, expect, test } from 'vitest';-import { isAllowedApiOrigin } from './api-origin.ts';+import { isAllowedApiOrigin, isOpaqueOrigin } from './api-origin.ts';describe('API origin guards', () => {- test('allows only local browser origins and opaque Electron origins', () => {- expect(isAllowedApiOrigin('null')).toBe(true);+ test('allows only local browser origins and refuses the null origin sandboxed frames send', () => {+ expect(isAllowedApiOrigin('null')).toBe(false);expect(isAllowedApiOrigin('http://localhost:5173')).toBe(true);expect(isAllowedApiOrigin('https://127.0.0.1:3000')).toBe(true);expect(isAllowedApiOrigin('http://[::1]:3000')).toBe(true);@@ -24,3 +24,20 @@ describe('isAllowedApiOrigin stays loopback-only', () => {expect(isAllowedApiOrigin('http://localhost:5173')).toBe(true);});});++describe('isOpaqueOrigin', () => {+ test('names the origins that do not identify a site: null and any file: origin', () => {+ expect(isOpaqueOrigin('null')).toBe(true);+ expect(isOpaqueOrigin('file://')).toBe(true);+ expect(isOpaqueOrigin('file://127.0.0.1')).toBe(true);+ expect(isOpaqueOrigin('FILE://')).toBe(true);+ });++ test('leaves site origins, including loopback and the literal host "null", alone', () => {+ expect(isOpaqueOrigin('http://localhost:5173')).toBe(false);+ expect(isOpaqueOrigin('http://127.0.0.1:3000')).toBe(false);+ expect(isOpaqueOrigin('https://example.com')).toBe(false);+ expect(isOpaqueOrigin('http://null')).toBe(false);+ expect(isOpaqueOrigin('Null')).toBe(false);+ });+});diff --git a/packages/server/src/api-origin.ts b/packages/server/src/api-origin.tsindex da5fdc4dd..8c5ae4718 100644--- a/packages/server/src/api-origin.ts+++ b/packages/server/src/api-origin.ts@@ -1,5 +1,15 @@+const SAFE_METHODS: ReadonlySet<string> = new Set(['GET', 'HEAD', 'OPTIONS']);++export function isSafeMethod(method: string | undefined): boolean {+ return SAFE_METHODS.has(method ?? 'GET');+}++export function isOpaqueOrigin(origin: string): boolean {+ return origin === 'null' || origin.toLowerCase().startsWith('file:');+}+export function isAllowedApiOrigin(origin: string): boolean {- if (origin === 'null' || origin === 'file://') return true;+ if (origin === 'file://') return true;try {const { hostname } = new URL(origin);return (diff --git a/packages/server/src/api-skills-composition.test.ts b/packages/server/src/api-skills-composition.test.tsindex 88fa9c7e5..7660bed14 100644--- a/packages/server/src/api-skills-composition.test.ts+++ b/packages/server/src/api-skills-composition.test.ts@@ -12,6 +12,8 @@ import {rawRequest,} from './composition-rig.test-helper.ts';+const LOOPBACK_ORIGIN = 'http://localhost:5173';+const SKILL_METHODS = [['/api/skills', 'GET'],['/api/skill', 'GET, PUT, POST, DELETE'],@@ -91,24 +93,27 @@ describe('skills contracts over the composed listener', () => {request.destroy();});- test('null Origin reaches catalog install and import validation but is refused by handoff admission', async () => {- for (const path of ['/api/skill/install', '/api/skill/import']) {- const catalog = await rawRequest(server.port, path, {+ test('null Origin is refused by the shared origin gate on every write, JSON included', async () => {+ for (const path of ['/api/skill/install', '/api/skill/import', '/api/install-skill']) {+ const res = await rawRequest(server.port, path, {method: 'POST',headers: { Origin: 'null', 'Content-Type': 'application/json' },body: '{}',});- expect(catalog.status, `${path}: ${catalog.body}`).toBe(400);- expect(parseProblem(catalog.body).type).toBe('urn:ok:error:invalid-request');- expect(parseProblem(catalog.body).title).toBe('Request body is invalid.');+ expect(res.status, `${path}: ${res.body}`).toBe(403);+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:invalid-origin');+ expect(res.headers['access-control-allow-origin'], path).toBeUndefined();+ }+ for (const path of ['/api/skill/install', '/api/skill/import']) {+ const loopback = await rawRequest(server.port, path, {+ method: 'POST',+ headers: { Origin: LOOPBACK_ORIGIN, 'Content-Type': 'application/json' },+ body: '{}',+ });+ expect(loopback.status, `${path}: ${loopback.body}`).toBe(400);+ expect(parseProblem(loopback.body).type, path).toBe('urn:ok:error:invalid-request');+ expect(parseProblem(loopback.body).title, path).toBe('Request body is invalid.');}- const handoff = await rawRequest(server.port, '/api/install-skill', {- method: 'POST',- headers: { Origin: 'null', 'Content-Type': 'application/json' },- body: '{}',- });- expect(handoff.status, handoff.body).toBe(403);- expect(parseProblem(handoff.body).type).toBe('urn:ok:error:invalid-origin');});test('both install routes accept consented external origins before parsing malformed JSON', async () => {diff --git a/packages/server/src/comments/comment-api.ts b/packages/server/src/comments/comment-api.tsindex a8191bd42..53c4ab11c 100644--- a/packages/server/src/comments/comment-api.ts+++ b/packages/server/src/comments/comment-api.ts@@ -11,7 +11,11 @@ import {import { z } from 'zod';import { extractActorIdentity } from '../extract-actor-identity.ts';import { errorResponse } from '../http/error-response.ts';-import { readBoundedJsonBody } from '../http/request-validation.ts';+import {+ readBoundedJsonBody,+ respondUnsupportedMediaType,+ UnsupportedMediaTypeError,+} from '../http/request-validation.ts';import { successResponse } from '../http/success-response.ts';import {type CommentService,@@ -294,7 +298,11 @@ async function parseBody<T extends z.ZodType>(let raw: Buffer;try {raw = await readBoundedJsonBody(req, BODY_LIMITS);- } catch {+ } catch (err) {+ if (err instanceof UnsupportedMediaTypeError) {+ respondUnsupportedMediaType(res, HANDLER);+ return null;+ }badRequest(res, 'Request body could not be read.');return null;}diff --git a/packages/server/src/handoff-dispatch-api.ts b/packages/server/src/handoff-dispatch-api.tsindex c75479029..49876d063 100644--- a/packages/server/src/handoff-dispatch-api.ts+++ b/packages/server/src/handoff-dispatch-api.ts@@ -13,6 +13,8 @@ import {PayloadTooLargeError,RequestBodyTimeoutError,readBoundedJsonBody,+ respondUnsupportedMediaType,+ UnsupportedMediaTypeError,} from './http/request-validation.ts';import { successResponse } from './http/success-response.ts';import { getLogger } from './logger.ts';@@ -131,6 +133,10 @@ export async function handleHandoffDispatch(timeoutMs: HANDOFF_BODY_READ_TIMEOUT_MS,});} catch (err) {+ if (err instanceof UnsupportedMediaTypeError) {+ respondUnsupportedMediaType(res, HANDLER);+ return;+ }if (err instanceof PayloadTooLargeError) {errorResponse(res, 413, 'urn:ok:error:payload-too-large', 'Payload too large.', {handler: HANDLER,diff --git a/packages/server/src/http/api-pipeline.test.ts b/packages/server/src/http/api-pipeline.test.tsindex 1338bb524..bda44c417 100644--- a/packages/server/src/http/api-pipeline.test.ts+++ b/packages/server/src/http/api-pipeline.test.ts@@ -26,17 +26,24 @@ interface NativeRig {port: number;baseUrl: string;legacyCalls: string[];+ dispatched: string[];close: () => Promise<void>;}async function bootNativeRig(opts: { ephemeral?: boolean } = {}): Promise<NativeRig> {const legacyCalls: string[] = [];+ const dispatched: string[] = [];const table: ApiRouteTable = {resolve(pathname) {- if (pathname === '/api/native-ping' || pathname === '/api/native-mutating') {+ if (+ pathname === '/api/native-ping' ||+ pathname === '/api/native-mutating' ||+ pathname === '/api/native-upload'+ ) {return {template: pathname,- dispatch: async (_req, res) => {+ dispatch: async (req, res) => {+ dispatched.push(`${req.method} ${pathname}`);res.writeHead(200, { 'Content-Type': 'application/json' });res.end(JSON.stringify({ pong: true }));},@@ -61,6 +68,7 @@ async function bootNativeRig(opts: { ephemeral?: boolean } = {}): Promise<Nativepaths: ['/api/native-ping','/api/native-mutating',+ '/api/native-upload','/api/native-throw','/api/native-empty','/api/native-declined',@@ -87,6 +95,7 @@ async function bootNativeRig(opts: { ephemeral?: boolean } = {}): Promise<Nativeport,baseUrl,legacyCalls,+ dispatched,close: () =>new Promise<void>((resolvePromise, reject) => {server.close((err) => (err ? reject(err) : resolvePromise()));@@ -178,9 +187,10 @@ describe('natively-mounted /api routes run the shared admission pipeline', () =>});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 };+ const body = (await res.json()) as { type?: string; title?: string; detail?: string };expect(body.type).toBe('urn:ok:error:invalid-origin');expect(body.title).toBe('Origin not allowed.');+ expect(body.detail).toBeUndefined();expect(res.headers.get('x-request-id')).not.toBeNull();} finally {await rig.close();@@ -308,6 +318,141 @@ describe('natively-mounted /api routes run the shared admission pipeline', () =>});});+describe('opaque origins and request body media types', () => {+ const OPAQUE_ORIGINS = ['null', 'file://', 'file://127.0.0.1'];+ const FILE_ORIGINS = ['file://', 'file://127.0.0.1'];+ const OPAQUE_DETAIL =+ 'Requests from a null origin, and writes from a file: origin, are refused. Send the request from a loopback page, the OpenKnowledge app, or a client that sends no Origin header.';++ function expectNoCorsGrant(headers: Record<string, string | string[] | undefined>): void {+ expect(headers['access-control-allow-origin']).toBeUndefined();+ expect(headers['access-control-allow-methods']).toBeUndefined();+ expect(headers['access-control-allow-headers']).toBeUndefined();+ expect(headers['access-control-expose-headers']).toBeUndefined();+ }++ test('a read from a null Origin is refused 403 before dispatch', async () => {+ const rig = await bootNativeRig();+ try {+ const res = await rawRequest(rig.port, '/api/native-ping', { headers: { Origin: 'null' } });+ expect(res.status).toBe(403);+ const problem = parseProblem(res.body);+ expect(problem.type).toBe('urn:ok:error:invalid-origin');+ expect(problem.detail).toBe(OPAQUE_DETAIL);+ expectNoCorsGrant(res.headers);+ expect(rig.dispatched).toEqual([]);+ } finally {+ await rig.close();+ }+ });++ test('a read from a file: Origin is served with no CORS grant, so a browser cannot read it', async () => {+ const rig = await bootNativeRig();+ try {+ for (const origin of FILE_ORIGINS) {+ const res = await rawRequest(rig.port, '/api/native-ping', { headers: { Origin: origin } });+ expect(res.status, origin).toBe(200);+ expectNoCorsGrant(res.headers);+ expect(res.headers.vary, origin).toContain('Origin');+ }+ } finally {+ await rig.close();+ }+ });++ test('an opaque-Origin preflight is not granted; a loopback preflight still is', async () => {+ const rig = await bootNativeRig();+ try {+ const preflight = (origin: string) =>+ rawRequest(rig.port, '/api/native-mutating', {+ method: 'OPTIONS',+ headers: {+ Origin: origin,+ 'Access-Control-Request-Method': 'POST',+ 'Access-Control-Request-Headers': 'content-type',+ },+ });+ for (const origin of OPAQUE_ORIGINS) {+ const res = await preflight(origin);+ expect(res.status, origin).toBe(origin === 'null' ? 403 : 204);+ expectNoCorsGrant(res.headers);+ }+ const loopback = await preflight('http://localhost:5173');+ expect(loopback.status).toBe(204);+ expect(loopback.headers['access-control-allow-origin']).toBe('http://localhost:5173');+ expect(loopback.headers['access-control-allow-headers']).toBe(EXPECTED_ALLOW_HEADERS);+ expect(rig.dispatched).toEqual([]);+ } finally {+ await rig.close();+ }+ });++ test('every write from an opaque Origin is refused 403 before dispatch, whatever its body', async () => {+ const rig = await bootNativeRig();+ try {+ const bodies: Array<{ headers: Record<string, string>; body?: string }> = [+ { headers: { 'Content-Type': 'application/json' }, body: '{"path":"x.md"}' },+ { headers: { 'Content-Type': 'text/plain' }, body: '{"path":"x.md"}' },+ { headers: { 'Content-Type': 'multipart/form-data; boundary=b' }, body: '--b--\r\n' },+ { headers: {} },+ ];+ for (const origin of OPAQUE_ORIGINS) {+ for (const method of ['POST', 'PUT', 'PATCH', 'DELETE']) {+ for (const path of ['/api/native-mutating', '/api/native-upload']) {+ for (const shape of bodies) {+ const res = await rawRequest(rig.port, path, {+ method,+ headers: { ...shape.headers, Origin: origin },+ ...(shape.body !== undefined ? { body: shape.body } : {}),+ });+ const label = `${origin} ${method} ${path} ${shape.headers['Content-Type'] ?? 'bodyless'}`;+ expect(res.status, label).toBe(403);+ const problem = parseProblem(res.body);+ expect(problem.type, label).toBe('urn:ok:error:invalid-origin');+ expect(problem.detail, label).toBe(OPAQUE_DETAIL);+ expectNoCorsGrant(res.headers);+ }+ }+ }+ }+ expect(rig.dispatched).toEqual([]);+ } finally {+ await rig.close();+ }+ });++ test('body media types are not gated at the pipeline layer: every shape reaches dispatch', async () => {+ const rig = await bootNativeRig();+ try {+ for (const [method, contentType, hasBody] of [+ ['POST', 'application/json', true],+ ['POST', 'text/plain', true],+ ['POST', 'multipart/form-data; boundary=b', true],+ ['POST', undefined, false],+ ['DELETE', 'text/plain', true],+ ['GET', 'text/plain', false],+ ] as const) {+ const res = await rawRequest(rig.port, '/api/native-mutating', {+ method,+ headers: contentType === undefined ? {} : { 'Content-Type': contentType },+ ...(hasBody ? { body: '{"path":"x.md"}' } : {}),+ });+ expect(res.status, `${method} ${contentType ?? 'bodyless'}`).toBe(200);+ }+ expect(rig.dispatched).toEqual([+ 'POST /api/native-mutating',+ 'POST /api/native-mutating',+ 'POST /api/native-mutating',+ 'POST /api/native-mutating',+ 'DELETE /api/native-mutating',+ 'GET /api/native-mutating',+ ]);+ } finally {+ await rig.close();+ }+ });+});+describe('createApiRouteGroup', () => {const handler = async () => {};diff --git a/packages/server/src/http/api-pipeline.ts b/packages/server/src/http/api-pipeline.tsindex e104fab95..8049212f0 100644--- a/packages/server/src/http/api-pipeline.ts+++ b/packages/server/src/http/api-pipeline.ts@@ -11,11 +11,11 @@ import {} from '@opentelemetry/semantic-conventions';import { recordEmbedProbe } from '../embed-probe.ts';import {+ admitRequestOrigin,buildIngressPolicy,HOST_NOT_ADMITTED_REMEDIATION,type IngressPolicy,isHostAdmitted,- isOriginAdmitted,isPeerAdmitted,stampIngressContext,} from '../ingress-policy.ts';@@ -201,23 +201,29 @@ export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPiif (url.startsWith('/api/')) {const origin = request.headers.origin;- if (origin !== undefined && !isOriginAdmitted(origin, policy)) {+ const admission = admitRequestOrigin(origin, method, policy);+ if (!admission.admitted) {errorResponse(response, 403, 'urn:ok:error:invalid-origin', 'Origin not allowed.', {handler: 'api-origin-gate',+ detail: admission.detail,});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');- 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}`,- );- response.setHeader('Access-Control-Expose-Headers', REQUEST_ID_HEADER);+ if (admission.corsGrant) {+ if (origin !== undefined) {+ response.setHeader('Access-Control-Allow-Origin', origin);+ }+ response.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');+ 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}`,+ );+ response.setHeader('Access-Control-Expose-Headers', REQUEST_ID_HEADER);+ }}if (request.method === 'OPTIONS') {response.writeHead(204);diff --git a/packages/server/src/http/mcp-route.ts b/packages/server/src/http/mcp-route.tsindex 89b60b581..afe5dddea 100644--- a/packages/server/src/http/mcp-route.ts+++ b/packages/server/src/http/mcp-route.ts@@ -1,9 +1,9 @@import type { IncomingMessage, ServerResponse } from 'node:http';import {+ admitRequestOrigin,HOST_NOT_ADMITTED_REMEDIATION,type IngressPolicy,isHostAdmitted,- isOriginAdmitted,isPeerAdmitted,} from '../ingress-policy.ts';import type { PinoLogger } from '../logger.ts';@@ -42,18 +42,24 @@ export function createMcpDispatch(});return;}- if (origin !== undefined && !isOriginAdmitted(origin, policy)) {+ const admission = admitRequestOrigin(origin, req.method, policy);+ if (!admission.admitted) {errorResponse(res, 403, 'urn:ok:error:invalid-origin', 'Origin not allowed.', {handler: 'mcp',+ detail: admission.detail,});return;}if (origin !== undefined) {- res.setHeader('Access-Control-Allow-Origin', origin);res.setHeader('Vary', 'Origin');}- for (const [header, value] of Object.entries(MCP_CORS_HEADERS)) {- res.setHeader(header, value);+ if (admission.corsGrant) {+ if (origin !== undefined) {+ res.setHeader('Access-Control-Allow-Origin', origin);+ }+ for (const [header, value] of Object.entries(MCP_CORS_HEADERS)) {+ res.setHeader(header, value);+ }}if (req.method === 'OPTIONS') {res.writeHead(204);diff --git a/packages/server/src/http/request-validation.test.ts b/packages/server/src/http/request-validation.test.tsindex cfce07a5c..daa00b61d 100644--- a/packages/server/src/http/request-validation.test.ts+++ b/packages/server/src/http/request-validation.test.ts@@ -2,8 +2,11 @@ import type { IncomingMessage, ServerResponse } from 'node:http';import { describe, expect, test } from 'vitest';import { z } from 'zod';import {+ isJsonContentType,PayloadTooLargeError,RequestBodyTimeoutError,+ readBoundedJsonBody,+ UnsupportedMediaTypeError,validateBody,withValidation,} from './request-validation.ts';@@ -30,11 +33,13 @@ interface MockReqOptions {method?: string;chunks?: Buffer[];throwOnRead?: Error;+ headers?: Record<string, string>;}function makeMockReq(opts: MockReqOptions = {}): IncomingMessage {return {method: opts.method ?? 'POST',+ headers: opts.headers ?? {},destroy(_err?: Error) {},[Symbol.asyncIterator]: async function* () {if (opts.throwOnRead) {@@ -384,3 +389,227 @@ describe('validateBody — direct unit tests (multipart handler entry point)', (expect(body.detail).toContain('field');});});++describe('withValidation: body media type gate', () => {+ const wrappedWithSpy = (options: Parameters<typeof withValidation>[2] = {}) => {+ const calls: string[] = [];+ const wrapped = withValidation(+ TestSchema,+ async () => {+ calls.push('handler');+ },+ { handler: 'test', ...options },+ );+ return { wrapped, calls };+ };++ const declaredBody = (headers: Record<string, string>, chunks = [Buffer.from('{"foo":"bar"}')]) =>+ makeMockReq({+ headers: { 'content-length': String(chunks[0]?.length ?? 0), ...headers },+ chunks,+ });++ test.each([+ ['text/plain'],+ ['text/plain;charset=UTF-8'],+ ['application/x-www-form-urlencoded'],+ ['multipart/form-data; boundary=b'],+ ['application/jsonp'],+ ['application/xml'],+ ])(+ 'a declared body typed %s → 415 problem+json, before the body is read',+ async (contentType) => {+ const { res, writeHeadCalls, endCalls } = makeMockRes();+ const { wrapped, calls } = wrappedWithSpy();+ let bodyConsumed = false;+ const req = makeMockReq({+ headers: { 'content-type': contentType, 'content-length': '13' },+ chunks: [Buffer.from('{"foo":"bar"}')],+ });+ Object.defineProperty(req, Symbol.asyncIterator, {+ value: async function* () {+ bodyConsumed = true;+ yield Buffer.from('{"foo":"bar"}');+ },+ });+ await wrapped(req, res);+ expect(calls).toEqual([]);+ expect(bodyConsumed).toBe(false);+ expect(writeHeadCalls.length).toBe(1);+ expect(writeHeadCalls[0].status).toBe(415);+ expect(writeHeadCalls[0].headers['Content-Type']).toBe('application/problem+json');+ const body = JSON.parse(endCalls[0]);+ expect(body.type).toBe('urn:ok:error:unsupported-media-type');+ expect(body.title).toBe('Request body must be JSON.');+ expect(body.status).toBe(415);+ expect(body.detail).toContain('Content-Type: application/json');+ },+ );++ test('a declared body with no content-type at all → 415', async () => {+ const { res, writeHeadCalls } = makeMockRes();+ const { wrapped, calls } = wrappedWithSpy();+ await wrapped(declaredBody({}), res);+ expect(calls).toEqual([]);+ expect(writeHeadCalls[0].status).toBe(415);+ });++ test.each([+ ['application/json'],+ ['application/json; charset=utf-8'],+ ['Application/JSON'],+ ['application/json ;charset=utf-8'],+ ['application/merge-patch+json'],+ ])('a body typed %s reaches the handler', async (contentType) => {+ const { res, writeHeadCalls } = makeMockRes();+ const { wrapped, calls } = wrappedWithSpy();+ await wrapped(declaredBody({ 'content-type': contentType }), res);+ expect(calls).toEqual(['handler']);+ expect(writeHeadCalls.length).toBe(0);+ });++ test('an undeclared body (no content-length, no transfer-encoding) skips the gate', async () => {+ const { res, writeHeadCalls } = makeMockRes();+ const { wrapped, calls } = wrappedWithSpy();+ await wrapped(+ makeMockReq({+ headers: { 'content-type': 'text/plain' },+ chunks: [Buffer.from('{"foo":"bar"}')],+ }),+ res,+ );+ expect(calls).toEqual(['handler']);+ expect(writeHeadCalls.length).toBe(0);+ });++ test('transfer-encoding alone declares a body → 415 without a content-type', async () => {+ const { res, writeHeadCalls } = makeMockRes();+ const { wrapped, calls } = wrappedWithSpy();+ await wrapped(makeMockReq({ headers: { 'transfer-encoding': 'chunked' } }), res);+ expect(calls).toEqual([]);+ expect(writeHeadCalls[0].status).toBe(415);+ });++ test('skipBodyParse routes ignore the body entirely, media type included', async () => {+ const { res, writeHeadCalls, endCalls } = makeMockRes();+ const { wrapped, calls } = wrappedWithSpy({ skipBodyParse: true, method: 'DELETE' });+ await wrapped(+ makeMockReq({+ method: 'DELETE',+ headers: { 'content-type': 'text/plain', 'content-length': '3' },+ chunks: [Buffer.from('{}')],+ }),+ res,+ );+ expect(calls).toEqual([]);+ expect(writeHeadCalls.length).toBe(1);+ expect(writeHeadCalls[0].status).toBe(400);+ expect(JSON.parse(endCalls[0]).type).toBe('urn:ok:error:invalid-request');+ });++ test('the method check outranks the media gate: a wrong method is still 405 with Allow', async () => {+ const { res, writeHeadCalls } = makeMockRes();+ const { wrapped, calls } = wrappedWithSpy({ method: 'POST' });+ await wrapped(+ makeMockReq({+ method: 'PATCH',+ headers: { 'content-type': 'text/plain', 'content-length': '13' },+ chunks: [Buffer.from('{"foo":"bar"}')],+ }),+ res,+ );+ expect(calls).toEqual([]);+ expect(writeHeadCalls[0].status).toBe(405);+ expect(writeHeadCalls[0].headers.Allow).toBe('POST');+ });++ test('a preBodyGate refusal still wins over the media gate', async () => {+ const { res, writeHeadCalls, endCalls } = makeMockRes();+ const wrapped = withValidation(+ TestSchema,+ async () => {+ throw new Error('handler must not run');+ },+ {+ handler: 'test',+ preBodyGate: (_req, response) => {+ response.writeHead(403, { 'Content-Type': 'application/problem+json' });+ response.end(JSON.stringify({ type: 'urn:ok:error:invalid-origin' }));+ (response as { headersSent?: boolean }).headersSent = true;+ (response as { writableEnded?: boolean }).writableEnded = true;+ return false;+ },+ },+ );+ await wrapped(+ makeMockReq({+ headers: { 'content-type': 'text/plain', 'content-length': '13' },+ chunks: [Buffer.from('{"foo":"bar"}')],+ }),+ res,+ );+ expect(writeHeadCalls.length).toBe(1);+ expect(writeHeadCalls[0].status).toBe(403);+ expect(JSON.parse(endCalls[0]).type).toBe('urn:ok:error:invalid-origin');+ });+});++describe('isJsonContentType', () => {+ test.each([+ ['application/json'],+ ['application/json; charset=utf-8'],+ ['APPLICATION/JSON'],+ ['Application/JSON'],+ [' application/json '],+ ['application/json ;charset=utf-8'],+ ['application/merge-patch+json'],+ ['application/json-patch+json'],+ ['application/vnd.api+json'],+ ])('admits %s', (contentType) => {+ expect(isJsonContentType(contentType)).toBe(true);+ });++ test.each([+ [undefined],+ [''],+ ['text/plain'],+ ['text/plain;charset=UTF-8'],+ ['multipart/form-data; boundary=x'],+ ['application/x-www-form-urlencoded'],+ ['application/jsonp'],+ ['application/+json'],+ ['text/json'],+ ['application/xml'],+ ])('refuses %s', (contentType) => {+ expect(isJsonContentType(contentType)).toBe(false);+ });+});++describe('readBoundedJsonBody: media type refusal', () => {+ const limits = { maxBytes: 1024, timeoutMs: 5_000 };++ test('throws UnsupportedMediaTypeError for a declared non-JSON body without reading it', async () => {+ let bodyConsumed = false;+ const req = makeMockReq({ headers: { 'content-type': 'text/plain', 'content-length': '2' } });+ Object.defineProperty(req, Symbol.asyncIterator, {+ value: async function* () {+ bodyConsumed = true;+ yield Buffer.from('{}');+ },+ });+ await expect(readBoundedJsonBody(req, limits)).rejects.toBeInstanceOf(+ UnsupportedMediaTypeError,+ );+ expect(bodyConsumed).toBe(false);+ });++ test('reads a JSON body and an undeclared body', async () => {+ const json = makeMockReq({+ headers: { 'content-type': 'application/json', 'content-length': '13' },+ chunks: [Buffer.from('{"foo":"bar"}')],+ });+ expect((await readBoundedJsonBody(json, limits)).toString('utf8')).toBe('{"foo":"bar"}');+ const undeclared = makeMockReq({ headers: { 'content-type': 'text/plain' } });+ expect((await readBoundedJsonBody(undeclared, limits)).length).toBe(0);+ });+});diff --git a/packages/server/src/http/request-validation.ts b/packages/server/src/http/request-validation.tsindex 534397fe3..8c2e3e0bc 100644--- a/packages/server/src/http/request-validation.ts+++ b/packages/server/src/http/request-validation.ts@@ -18,10 +18,26 @@ function readRequestBody(req: IncomingMessage): Promise<Buffer> {});}+export function isJsonContentType(contentType: string | undefined): boolean {+ const mediaType = contentType?.split(';', 1)[0]?.trim().toLowerCase();+ if (mediaType === undefined) return false;+ return (+ mediaType === 'application/json' || /^application\/[a-z0-9!#$&^_.+-]+\+json$/.test(mediaType)+ );+}++function hasRequestBody(req: IncomingMessage): boolean {+ if (req.headers['transfer-encoding'] !== undefined) return true;+ return Number(req.headers['content-length'] ?? 0) > 0;+}+export async function readBoundedJsonBody(req: IncomingMessage,opts: { readonly maxBytes: number; readonly timeoutMs: number },): Promise<Buffer> {+ if (hasRequestBody(req) && !isJsonContentType(req.headers['content-type'])) {+ throw new UnsupportedMediaTypeError();+ }const chunks: Buffer[] = [];let totalBytes = 0;const timeoutSignal = AbortSignal.timeout(opts.timeoutMs);@@ -41,6 +57,23 @@ export async function readBoundedJsonBody(}}+export class UnsupportedMediaTypeError extends Error {+ constructor() {+ super('Request body is not labeled as JSON');+ this.name = 'UnsupportedMediaTypeError';+ }+}++export function respondUnsupportedMediaType(+ res: ServerResponse,+ handler: string | undefined,+): void {+ errorResponse(res, 415, 'urn:ok:error:unsupported-media-type', 'Request body must be JSON.', {+ handler,+ detail: 'Send the request body as JSON with the header Content-Type: application/json.',+ });+}+export class PayloadTooLargeError extends Error {readonly maxBytes?: number;constructor(maxBytes?: number) {@@ -144,6 +177,10 @@ export function withValidation<T>(try {raw = await readRequestBody(req);} catch (err) {+ if (err instanceof UnsupportedMediaTypeError) {+ respondUnsupportedMediaType(res, options.handler);+ return;+ }if (err instanceof PayloadTooLargeError) {errorResponse(res, 413, 'urn:ok:error:payload-too-large', 'Payload too large.', {handler: options.handler,diff --git a/packages/server/src/http/share-routes.test.ts b/packages/server/src/http/share-routes.test.tsindex f7b8f9512..eba422a63 100644--- a/packages/server/src/http/share-routes.test.ts+++ b/packages/server/src/http/share-routes.test.ts@@ -52,6 +52,7 @@ describe('createShareRoutes table', () => {]) as IncomingMessage;req.method = 'POST';req.url = '/api/share/construct-url';+ req.headers = { 'content-type': 'application/json', 'transfer-encoding': 'chunked' };const { res, captured } = makeCaptureRes();const route = group.table.resolve(req.url);if (!route?.dispatch) throw new Error('missing construct-url handler');diff --git a/packages/server/src/http/workspace-tools-routes.ts b/packages/server/src/http/workspace-tools-routes.tsindex f36c5cfeb..d07aed6a4 100644--- a/packages/server/src/http/workspace-tools-routes.ts+++ b/packages/server/src/http/workspace-tools-routes.ts@@ -59,7 +59,7 @@ import { catchErrors } from './catch-errors.ts';import { errorResponse } from './error-response.ts';import { parseQuery } from './handler-utils.ts';import { methodRouter } from './method-router.ts';-import { withValidation } from './request-validation.ts';+import { respondUnsupportedMediaType, withValidation } from './request-validation.ts';import { successResponse } from './success-response.ts';const GeneratedIndexSettingsStatusSchema = z.object({@@ -107,13 +107,7 @@ function loopbackJsonGate(handler: string): (req: IncomingMessage, res: ServerReif (verdict.reason === 'origin') {errorResponse(res, 403, 'urn:ok:error:invalid-origin', 'Origin not allowed.', { handler });} else {- errorResponse(- res,- 400,- 'urn:ok:error:invalid-request',- 'Content-Type must be application/json.',- { handler },- );+ respondUnsupportedMediaType(res, handler);}return false;};diff --git a/packages/server/src/ingress-policy.test.ts b/packages/server/src/ingress-policy.test.tsindex cbf8554ea..85d34be14 100644--- a/packages/server/src/ingress-policy.test.ts+++ b/packages/server/src/ingress-policy.test.ts@@ -1,6 +1,7 @@import type { ServerRuntimeConfig } from '@inkeep/open-knowledge-core';import { describe, expect, test } from 'vitest';import {+ admitRequestOrigin,buildIngressPolicy,getIngressContext,hasForwardingHeaders,@@ -9,6 +10,7 @@ import {isOriginAdmitted,isPeerAdmitted,normalizeHostHeader,+ OPAQUE_ORIGIN_REFUSAL_DETAIL,stampIngressContext,tripsForwardedHeaderTripwire,} from './ingress-policy.ts';@@ -194,10 +196,11 @@ describe('isOriginAdmitted — if present, must match; scheme-matched for externexpect(isOriginAdmitted('ftp://100.64.0.7', bound)).toBe(false);});- test('loopback and the Electron null/file shapes always pass', () => {+ test('loopback and the desktop file:// shape pass; the sandboxed-frame null origin never does', () => {const local = buildIngressPolicy({});expect(isOriginAdmitted('http://localhost:5173', local)).toBe(true);- expect(isOriginAdmitted('null', local)).toBe(true);+ expect(isOriginAdmitted('null', local)).toBe(false);+ expect(isOriginAdmitted('null', case3)).toBe(false);expect(isOriginAdmitted('file://', local)).toBe(true);expect(isOriginAdmitted('https://evil.example.com', local)).toBe(false);});@@ -302,3 +305,48 @@ describe('ingress request context', () => {expect(getIngressContext(req)).toBe(context);});});++describe('admitRequestOrigin', () => {+ const local = buildIngressPolicy({});+ const opaqueRefusal = { admitted: false, detail: OPAQUE_ORIGIN_REFUSAL_DETAIL };++ test('no Origin and site origins are admitted with the CORS grant', () => {+ expect(admitRequestOrigin(undefined, 'POST', local)).toEqual({+ admitted: true,+ corsGrant: true,+ });+ expect(admitRequestOrigin('http://localhost:5173', 'GET', local)).toEqual({+ admitted: true,+ corsGrant: true,+ });+ expect(admitRequestOrigin('http://127.0.0.1:4000', 'DELETE', local)).toEqual({+ admitted: true,+ corsGrant: true,+ });+ });++ test('a null origin is refused for every method with the opaque-origin detail', () => {+ for (const method of ['GET', 'HEAD', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']) {+ expect(admitRequestOrigin('null', method, local), method).toEqual(opaqueRefusal);+ }+ });++ test('a file: origin may read without a grant and may not write', () => {+ for (const method of ['GET', 'HEAD', 'OPTIONS']) {+ expect(admitRequestOrigin('file://', method, local), method).toEqual({+ admitted: true,+ corsGrant: false,+ });+ }+ for (const method of ['POST', 'PUT', 'PATCH', 'DELETE']) {+ expect(admitRequestOrigin('file://', method, local), method).toEqual(opaqueRefusal);+ }+ });++ test('a foreign origin is refused without the opaque-origin detail', () => {+ expect(admitRequestOrigin('https://evil.example', 'GET', local)).toEqual({+ admitted: false,+ detail: undefined,+ });+ });+});diff --git a/packages/server/src/ingress-policy.ts b/packages/server/src/ingress-policy.tsindex ef35c96ac..9c09c818b 100644--- a/packages/server/src/ingress-policy.ts+++ b/packages/server/src/ingress-policy.ts@@ -1,6 +1,6 @@import type { IncomingMessage } from 'node:http';import type { ServerRuntimeConfig } from '@inkeep/open-knowledge-core';-import { isAllowedApiOrigin } from './api-origin.ts';+import { isAllowedApiOrigin, isOpaqueOrigin, isSafeMethod } from './api-origin.ts';import type { PinoLogger } from './logger.ts';import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';@@ -131,6 +131,26 @@ export function isOriginAdmitted(origin: string, policy: IngressPolicy): booleanreturn false;}+export const OPAQUE_ORIGIN_REFUSAL_DETAIL =+ 'Requests from a null origin, and writes from a file: origin, are refused. Send the request from a loopback page, the OpenKnowledge app, or a client that sends no Origin header.';++export type OriginAdmission =+ | { readonly admitted: true; readonly corsGrant: boolean }+ | { readonly admitted: false; readonly detail: string | undefined };++export function admitRequestOrigin(+ origin: string | undefined,+ method: string | undefined,+ policy: IngressPolicy,+): OriginAdmission {+ if (origin === undefined) return { admitted: true, corsGrant: true };+ const opaque = isOpaqueOrigin(origin);+ if (!isOriginAdmitted(origin, policy) || (opaque && !isSafeMethod(method))) {+ return { admitted: false, detail: opaque ? OPAQUE_ORIGIN_REFUSAL_DETAIL : undefined };+ }+ return { admitted: true, corsGrant: !opaque };+}+export function tripsForwardedHeaderTripwire(req: Pick<IncomingMessage, 'headers'>,policy: IngressPolicy,diff --git a/packages/server/src/link-preview/request-gate.test.ts b/packages/server/src/link-preview/request-gate.test.tsindex 4fade565e..6ffd59a0b 100644--- a/packages/server/src/link-preview/request-gate.test.ts+++ b/packages/server/src/link-preview/request-gate.test.ts@@ -1,9 +1,5 @@import { describe, expect, test } from 'vitest';-import {- classifyLinkPreviewRequest,- isJsonContentType,- isLoopbackHttpOrigin,-} from './request-gate.ts';+import { classifyLinkPreviewRequest, isLoopbackHttpOrigin } from './request-gate.ts';describe('isLoopbackHttpOrigin', () => {test.each([@@ -34,29 +30,6 @@ describe('isLoopbackHttpOrigin', () => {});});-describe('isJsonContentType', () => {- test.each([- ['application/json', true],- ['application/json; charset=utf-8', true],- ['APPLICATION/JSON', true],- [' application/json ', true],- ] as const)('admits JSON content type %s', (ct, expected) => {- expect(isJsonContentType(ct)).toBe(expected);- });-- test.each([- [undefined, 'missing'],- ['', 'empty'],- ['text/plain', 'simple-request text'],- ['text/plain;charset=UTF-8', 'simple-request text with charset'],- ['multipart/form-data; boundary=x', 'simple-request multipart'],- ['application/x-www-form-urlencoded', 'simple-request form'],- ['application/json-patch+json', 'json-adjacent but not json'],- ] as const)('rejects %s content type (%s)', (ct, _why) => {- expect(isJsonContentType(ct)).toBe(false);- });-});-describe('classifyLinkPreviewRequest', () => {test('admits a loopback-origin JSON POST', () => {expect(@@ -89,6 +62,16 @@ describe('classifyLinkPreviewRequest', () => {});});+ test.each([+ ['application/json; charset=utf-8'],+ ['Application/JSON'],+ ['application/merge-patch+json'],+ ] as const)('admits %s, the same JSON types the body reader accepts', (contentType) => {+ expect(classifyLinkPreviewRequest({ origin: 'http://localhost:5173', contentType })).toEqual({+ ok: true,+ });+ });+test('origin is judged before content type', () => {expect(classifyLinkPreviewRequest({ origin: 'null', contentType: 'text/plain' })).toEqual({ok: false,diff --git a/packages/server/src/link-preview/request-gate.ts b/packages/server/src/link-preview/request-gate.tsindex ec3b46f06..2a23b28b8 100644--- a/packages/server/src/link-preview/request-gate.ts+++ b/packages/server/src/link-preview/request-gate.ts@@ -1,3 +1,5 @@+import { isJsonContentType } from '../http/request-validation.ts';+/** @lintignore Referenced by the exported LinkPreviewGateVerdict type; no direct importer. */export type LinkPreviewGateRejection = 'origin' | 'content-type';@@ -16,12 +18,6 @@ export function isLoopbackHttpOrigin(origin: string | undefined): boolean {return host === 'localhost' || host === '[::1]' || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);}-export function isJsonContentType(contentType: string | undefined): boolean {- if (!contentType) return false;- const base = contentType.split(';', 1)[0]?.trim().toLowerCase();- return base === 'application/json';-}-export function classifyLinkPreviewRequest(headers: {origin: string | undefined;contentType: string | undefined;diff --git a/packages/server/src/spawn-cursor-api.ts b/packages/server/src/spawn-cursor-api.tsindex 0c2f94e17..e5ccee98e 100644--- a/packages/server/src/spawn-cursor-api.ts+++ b/packages/server/src/spawn-cursor-api.ts@@ -16,6 +16,8 @@ import {PayloadTooLargeError,RequestBodyTimeoutError,readBoundedJsonBody,+ respondUnsupportedMediaType,+ UnsupportedMediaTypeError,} from './http/request-validation.ts';import { successResponse } from './http/success-response.ts';import { getLogger } from './logger.ts';@@ -66,6 +68,10 @@ export async function handleSpawnCursor(timeoutMs: SPAWN_CURSOR_BODY_READ_TIMEOUT_MS,});} catch (err) {+ if (err instanceof UnsupportedMediaTypeError) {+ respondUnsupportedMediaType(res, HANDLER);+ return;+ }if (err instanceof PayloadTooLargeError) {errorResponse(res, 413, 'urn:ok:error:payload-too-large', 'Payload too large.', {handler: HANDLER,