Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(ok): Ingress consolidation + remote enablement (PRD-7879) (#3382)
omar-inkeepfdb72d6ca2fa
diff --git a/.changeset/wave4-ingress-remote-enablement.md b/.changeset/wave4-ingress-remote-enablement.mdnew file mode 100644index 000000000..b39151b3b--- /dev/null+++ b/.changeset/wave4-ingress-remote-enablement.md@@ -0,0 +1,13 @@+---+'@inkeep/open-knowledge': minor+---++Remote enablement: the `server.*` configuration keys now drive real behavior, and the server's ingress runs through one consolidated admission path.++- Environment variables land per the ratified mapping: `PORT`, `OK_BIND` (space-separated list), `OK_PUBLIC_URL`, `OK_ALLOW_EXTERNAL`, `OK_OPEN_BROWSER`, `OK_IDLE_SHUTDOWN`. Booleans accept `1`/`0`/`true`/`false`; a malformed value refuses to boot naming the variable. Precedence is flags > env > project-local > project > user config.+- `server.bind` is a real list: every configured address gets a listener on the same port. `server.publicUrl` feeds Host/Origin validation and issued URLs.+- The exposure consent interlock is enforced: a non-loopback bind without `server.allowExternal` refuses to boot with a one-line fix. A committed `server.publicUrl` under a loopback bind is inert metadata — it never blocks a teammate who clones a deploy repo and opens it locally; publicUrl's consent requirement surfaces at request time. Consent relaxes the loopback-peer check only — Host and Origin always validate against loopback names, the bind-address literals, and the configured public URL. Behind a reverse proxy or tunnel, forwarded headers are tolerated (never trusted) once consent and `server.publicUrl` are set.+- `.ok/local/config.yml` (the per-machine layer) now participates in CLI config loading with per-key scope ownership, so a committed `server.allowExternal: true` can never arm exposure on another machine.+- Starting an exposed server (`server.allowExternal` on a non-loopback bind or with a `publicUrl`) prints an unmissable warning: there is no server-side authentication, so anyone who can reach it has full control including sync, publishing, GitHub credentials, and local operations — restrict access at the edge (Tailscale ACL, an authenticating reverse proxy, or a firewall).+- The editor renders on plain-HTTP non-localhost origins (a tailnet or LAN IP, direct-IP access). `crypto.randomUUID()` is a secure-context-only API and was throwing at module load on those origins, leaving a blank screen; identity generation now falls back to `crypto.getRandomValues` when `randomUUID` is unavailable.+- `ok start --idle-shutdown off` no longer self-terminates on boot: an off flag now threads through to disable idle-shutdown identically to the exposed-bind derived default.diff --git a/packages/app/src/components/EditorActivityPool.tsx b/packages/app/src/components/EditorActivityPool.tsxindex 0fe5bc200..87eb55807 100644--- a/packages/app/src/components/EditorActivityPool.tsx+++ b/packages/app/src/components/EditorActivityPool.tsx@@ -39,6 +39,7 @@ import {isManagedArtifactDocName,isMermaidDocFile,parseTemplateContentDocName,+ randomUUID,} from '@inkeep/open-knowledge-core';import { t } from '@lingui/core/macro';import { RefreshCw } from 'lucide-react';@@ -524,7 +525,7 @@ function EditorActivityPoolInner({for (const docName of newlyMounted) {const entry = poolEntriesRef.current.find((e) => e.docName === docName);const adopted = entry?.poolEventId;- const mountId = adopted && adopted.length > 0 ? adopted : crypto.randomUUID();+ const mountId = adopted && adopted.length > 0 ? adopted : randomUUID();setMountId(docName, mountId);}mark('ok/activity/mount-list-change', {diff --git a/packages/app/src/editor/TiptapEditor.tsx b/packages/app/src/editor/TiptapEditor.tsxindex 52c92fbc2..beb0d8211 100644--- a/packages/app/src/editor/TiptapEditor.tsx+++ b/packages/app/src/editor/TiptapEditor.tsx@@ -8,6 +8,7 @@ import {FLASH_DURATION_MS,hasNewEntries,MarkdownManager,+ randomUUID,} from '@inkeep/open-knowledge-core';import { t } from '@lingui/core/macro';import { type AnyExtension, Editor, type EditorOptions, Extension } from '@tiptap/core';@@ -726,7 +727,7 @@ export const TiptapEditor: FC<TiptapEditorProps> = ({// hasn't run yet (rare race during first-render of a doc that bypasses// the pool's mount-list — e.g. direct navigation before the pool's// promote effect lands).- const mountId = getMountId(docName) ?? crypto.randomUUID();+ const mountId = getMountId(docName) ?? randomUUID();const entry = use(mountTiptapEditorPromise({ docName, mountId, construct, sizeStats }));const editor = entry.editor;diff --git a/packages/app/src/editor/image-upload/index.ts b/packages/app/src/editor/image-upload/index.tsindex 94cc544a4..658213721 100644--- a/packages/app/src/editor/image-upload/index.ts+++ b/packages/app/src/editor/image-upload/index.ts@@ -7,6 +7,7 @@ import {formatFileSize,IMAGE_EXTENSIONS,ProblemDetailsSchema,+ randomUUID,type UploadAssetSuccess,UploadAssetSuccessSchema,VIDEO_EXTENSIONS,@@ -290,7 +291,7 @@ export async function uploadAndInsert(toast.error(t`Cannot upload: no document is open`);return;}- const uploadId = crypto.randomUUID();+ const uploadId = randomUUID();// Sampled before any await: `File.size` re-stats the backing store, so once// that store is gone it reads 0 and the original size is unrecoverable.const sizeAtDrop = file.size;diff --git a/packages/app/src/editor/mount-promise.ts b/packages/app/src/editor/mount-promise.tsindex 780dd69e2..6782a43f2 100644--- a/packages/app/src/editor/mount-promise.ts+++ b/packages/app/src/editor/mount-promise.ts@@ -129,7 +129,7 @@ interface MountTiptapEditorPromiseParams {* sync, cold, and typing namespaces join deterministically by mountId* equality (no timestamp-window joins).*- * Caller derives via `getMountId(docName) ?? crypto.randomUUID()` —+ * Caller derives via `getMountId(docName) ?? randomUUID()` —* adopting an existing pool-derived id when present so prewarm-then-click* flows correlate across the pool→mount boundary. See mount-id-registry.ts* for the adoption invariant.diff --git a/packages/app/src/editor/provider-pool.ts b/packages/app/src/editor/provider-pool.tsindex f58b9d28a..48df5e3a0 100644--- a/packages/app/src/editor/provider-pool.ts+++ b/packages/app/src/editor/provider-pool.ts@@ -5,6 +5,7 @@ import {LINEAGE_EPOCH_KEY,MarkdownManager,normalizeBridge,+ randomUUID,stripFrontmatter,} from '@inkeep/open-knowledge-core';import type { HocuspocusAuthRejectionReason } from '@inkeep/open-knowledge-server';@@ -1894,7 +1895,7 @@ export class ProviderPool {}}- const poolEventId = crypto.randomUUID();+ const poolEventId = randomUUID();const entry: ActivePoolEntry = {kind: 'active',provider,diff --git a/packages/app/src/editor/tab-identity.ts b/packages/app/src/editor/tab-identity.tsindex 833ea83fb..16c66facd 100644--- a/packages/app/src/editor/tab-identity.ts+++ b/packages/app/src/editor/tab-identity.ts@@ -9,4 +9,10 @@* a single `refs/wip/<branch>/<principalId>` ref.*/-export const tabSessionId: string = crypto.randomUUID();+import { randomUUID } from '@inkeep/open-knowledge-core';++// `randomUUID` (not `crypto.randomUUID`) is load-bearing here: this runs at+// module load, and `crypto.randomUUID` is undefined on a plain-HTTP+// non-localhost origin (an exposed server over a tailnet/LAN IP), which would+// throw before React mounts. See randomUUID's contract.+export const tabSessionId: string = randomUUID();diff --git a/packages/cli/src/commands/config.test.ts b/packages/cli/src/commands/config.test.tsindex bf9772916..074561e3d 100644--- a/packages/cli/src/commands/config.test.ts+++ b/packages/cli/src/commands/config.test.ts@@ -247,7 +247,11 @@ describe('runValidate', () => {const project = makeTempProject();try {const wsPath = projectConfigPath(project.cwd);- writeConfigYaml(wsPath, `appearance:\n theme: midnight\n`);+ // A project-scoped invalid value (server.port out of range) survives the+ // scope-aware merge and fails the single merged parse — user-scoped keys+ // like appearance.theme are dropped before validation now, so they can't+ // exercise the source-location path from the project file.+ writeConfigYaml(wsPath, `server:\n port: 99999999\n`);const stderr: string[] = [];const outcome = runValidate({cwd: project.cwd,diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.tsindex 49c9e8060..7eb600531 100644--- a/packages/cli/src/commands/start.test.ts+++ b/packages/cli/src/commands/start.test.ts@@ -5,7 +5,7 @@ import { request as httpRequest } from 'node:http';import { hostname, tmpdir } from 'node:os';import { join, resolve } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';-import { LOCAL_DIR } from '@inkeep/open-knowledge-core';+import { idleShutdownToMs, LOCAL_DIR } from '@inkeep/open-knowledge-core';import { type Config, ConfigSchema } from '@inkeep/open-knowledge-server';import { afterEach, beforeEach, describe, expect, test } from 'vitest';import {@@ -33,6 +33,7 @@ import {resolveStartShellDir,shouldConnectToExistingServer,shouldOpenBrowser,+ shouldWarnHostOverridesMultiBind,spawnOkUi,startCommand,teardownUiSibling,@@ -2391,6 +2392,7 @@ describe('isLoopbackHost', () => {describe('shouldOpenBrowser (interactive-loopback default open)', () => {const base = {openBrowser: true,+ explicitOn: false,legacyOpen: false,host: '127.0.0.1',isTTY: true,@@ -2404,6 +2406,14 @@ describe('shouldOpenBrowser (interactive-loopback default open)', () => {expect(shouldOpenBrowser({ ...base })).toBe(true);});+ test('explicit openBrowser=true (config/env) lifts the loopback-bind condition', () => {+ expect(shouldOpenBrowser({ ...base, host: '100.64.0.7', explicitOn: true })).toBe(true);+ });++ test('explicit openBrowser=true still never opens without a TTY (container safety)', () => {+ expect(shouldOpenBrowser({ ...base, explicitOn: true, isTTY: false })).toBe(false);+ });+test('--no-open-browser suppresses', () => {expect(shouldOpenBrowser({ ...base, openBrowser: false })).toBe(false);});@@ -2593,15 +2603,39 @@ describe('formatServerReuseNotice', () => {});});+describe('shouldWarnHostOverridesMultiBind', () => {+ const base = { flagBindSet: false, okBindSet: false, hostEnvSet: true, fileBindCount: 2 };+ test('warns when HOST alone drives the bind over a multi-element file list', () => {+ expect(shouldWarnHostOverridesMultiBind(base)).toBe(true);+ });+ test('boundary: a single-element (or empty) file bind does NOT warn (> 1, not >= 1)', () => {+ expect(shouldWarnHostOverridesMultiBind({ ...base, fileBindCount: 1 })).toBe(false);+ expect(shouldWarnHostOverridesMultiBind({ ...base, fileBindCount: 0 })).toBe(false);+ });+ test('does not warn when a flag or OK_BIND is the bind source (HOST is not)', () => {+ expect(shouldWarnHostOverridesMultiBind({ ...base, flagBindSet: true })).toBe(false);+ expect(shouldWarnHostOverridesMultiBind({ ...base, okBindSet: true })).toBe(false);+ });+ test('does not warn when HOST is unset', () => {+ expect(shouldWarnHostOverridesMultiBind({ ...base, hostEnvSet: false })).toBe(false);+ });+});+describe('parseIdleShutdownFlag (--idle-shutdown, Table 3 semantics)', () => {- test("'off' disables idle shutdown (null)", () => {- expect(parseIdleShutdownFlag('off')).toBeNull();+ test("'off' is preserved as a string (idleShutdownToMs maps it to null)", () => {+ // The flag deliberately stays a string through Commander — returning `null`+ // here would be silently coerced to `''` by Commander and read downstream+ // as a 0 ms threshold (idle-shutdown fires on boot).+ expect(parseIdleShutdownFlag('off')).toBe('off');+ expect(idleShutdownToMs(parseIdleShutdownFlag('off'))).toBeNull();});- test('parses s/m/h durations to ms', () => {- expect(parseIdleShutdownFlag('90s')).toBe(90_000);- expect(parseIdleShutdownFlag('30m')).toBe(1_800_000);- expect(parseIdleShutdownFlag('2h')).toBe(7_200_000);+ test('valid durations pass through as strings (converted to ms at the boundary)', () => {+ expect(parseIdleShutdownFlag('90s')).toBe('90s');+ expect(parseIdleShutdownFlag('30m')).toBe('30m');+ expect(parseIdleShutdownFlag('2h')).toBe('2h');+ expect(idleShutdownToMs(parseIdleShutdownFlag('90s'))).toBe(90_000);+ expect(idleShutdownToMs(parseIdleShutdownFlag('2h'))).toBe(7_200_000);});test('rejects unitless, zero-led, and unknown-unit values', () => {@@ -2611,6 +2645,44 @@ describe('parseIdleShutdownFlag (--idle-shutdown, Table 3 semantics)', () => {});});+describe('--idle-shutdown threading through Commander (regression)', () => {+ // Exercises the REAL option registration end-to-end. Before the fix,+ // parseIdleShutdownFlag returned `null` for 'off'; Commander coerced that to+ // `''`, which `bootStartServer` read as a 0 ms idle threshold and the server+ // self-terminated on boot. A parseIdleShutdownFlag unit test cannot catch+ // this — the mangling happens inside Commander, not the parser.+ async function captureParsedOpts(argv: string[]): Promise<Record<string, unknown>> {+ const cmd = startCommand(() => makeTestConfig());+ cmd.exitOverride();+ cmd.configureOutput({ writeOut: () => {}, writeErr: () => {} });+ // Replace the boot action with a capture (last .action wins in Commander)+ // so parsing does not stand up a server.+ let captured: Record<string, unknown> = {};+ cmd.action((opts: Record<string, unknown>) => {+ captured = opts;+ });+ await cmd.parseAsync(argv, { from: 'user' });+ return captured;+ }++ test('--idle-shutdown off survives Commander and resolves to null (no idle shutdown)', async () => {+ const opts = await captureParsedOpts(['--idle-shutdown', 'off']);+ expect(opts.idleShutdown).toBe('off');+ expect(idleShutdownToMs(opts.idleShutdown as string)).toBeNull();+ });++ test('--idle-shutdown 90s survives Commander and resolves to 90000 ms', async () => {+ const opts = await captureParsedOpts(['--idle-shutdown', '90s']);+ expect(opts.idleShutdown).toBe('90s');+ expect(idleShutdownToMs(opts.idleShutdown as string)).toBe(90_000);+ });++ test('no --idle-shutdown flag leaves the value undefined (derived default applies)', async () => {+ const opts = await captureParsedOpts([]);+ expect(opts.idleShutdown).toBeUndefined();+ });+});+describe('startCommand — flag-conflict guards (exit 2)', () => {function quietCommand() {const cmd = startCommand(() => makeTestConfig());@@ -2651,11 +2723,9 @@ describe('startCommand — flag-conflict guards (exit 2)', () => {return { code, stderr };}- test('multiple --bind addresses exit 2', async () => {- const { code, stderr } = await captureGuard(['--bind', '127.0.0.1', '--bind', '10.0.0.1']);- expect(code).toBe(2);- expect(stderr).toContain('--bind');- });+ // The wave3 "multiple --bind exit 2" guard test was removed here —+ // multi-address bind is now real (guard dropped in start.ts; behavior+ // covered by the multi-bind boot tests in boot.test.ts).test('--server-url without --only ui exits 2', async () => {const { code, stderr } = await captureGuard(['--server-url', 'http://127.0.0.1:24550']);diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.tsindex 0f851b90e..b1e393a02 100644--- a/packages/cli/src/commands/start.ts+++ b/packages/cli/src/commands/start.ts@@ -34,8 +34,16 @@ import type { Server as HttpServer } from 'node:http';import { basename, join, resolve as pathResolve } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';import {+ applyConfigOverlay,DEFAULT_REMOTE_PORT,DEFAULT_SERVER_HOST,+ type EnvConfigLayer,+ EnvVarError,+ IDLE_SHUTDOWN_DURATION_RE,+ idleShutdownToMs,+ resolveEnvConfigLayer,+ resolveServerRuntimeConfig,+ type ServerRuntimeConfig,DEFAULT_SIGTERM_GRACE_MS as SHARED_DEFAULT_SIGTERM_GRACE_MS,DEFAULT_SIGTERM_POLL_MS as SHARED_DEFAULT_SIGTERM_POLL_MS,SPAWN_ERROR_LOG,@@ -65,12 +73,11 @@ import { resolveSelfSpawn } from './self-spawn.ts';const DEFAULT_IDLE_THRESHOLD_MS = 30 * 60 * 1000;/**- * Resolve server bind host with `--bind` flag > deprecated `--host` alias >+ * Resolve a single bind host with `--bind` flag > deprecated `--host` alias >* `HOST` env > application default precedence. Pure helper — no side effects,* no `process.env` access inside (env passed in) so tests can pin all- * branches. `--bind` is declared repeatable (the config surface reserves a- * bind LIST); the action layer rejects >1 value until multi-bind lands, so- * only the first element is consulted here.+ * branches. Used by the ephemeral single-file path; `ok start` proper+ * resolves the full bind LIST (config/env layers included) inline.*/export function resolveHost(opts: { host?: string; bind?: string[] },@@ -139,25 +146,23 @@ export function resolveStartShellDir(input: {/*** Validator for `--idle-shutdown <dur|off>`: `off`, or a strict `<n>(s|m|h)`- * duration. Returns milliseconds, or `null` for `off` (idle shutdown- * disabled). The grammar mirrors the forthcoming `server.idleShutdown` config- * leaf so the flag and the key resolve durations identically.+ * duration. Returns the validated string unchanged — conversion to ms (or+ * `null` for `off`) happens at the boot boundary via {@link idleShutdownToMs},+ * exactly as the env/file/derived `server.idleShutdown` value does, so the flag+ * and the key resolve identically. The grammar mirrors the `server.idleShutdown`+ * leaf via `IDLE_SHUTDOWN_DURATION_RE`.+ *+ * Returning the string (not the ms number / `null`) is load-bearing: Commander+ * silently coerces a `null`/`undefined` option-parser result to `''`, which the+ * downstream `?? DEFAULT` misses and the idle timer reads as `0` ms — firing+ * idle-shutdown on boot. A non-empty string survives Commander intact.*/-export function parseIdleShutdownFlag(value: string): number | null {- if (value === 'off') return null;- const match = /^([1-9]\d*)(s|m|h)$/.exec(value);- if (match === null) {+export function parseIdleShutdownFlag(value: string): string {+ if (value === 'off') return 'off';+ if (!IDLE_SHUTDOWN_DURATION_RE.test(value)) {throw new InvalidArgumentError("--idle-shutdown must be 'off' or a duration like 90s, 30m, 2h");}- const amount = Number(match[1]);- switch (match[2]) {- case 's':- return amount * 1000;- case 'm':- return amount * 60_000;- default:- return amount * 3_600_000;- }+ return value;}/** Loopback-shaped bind hosts — the family the browser-open default keys on. */@@ -165,6 +170,23 @@ export function isLoopbackHost(host: string): boolean {return host === 'localhost' || host === '::1' || host === '[::1]' || host.startsWith('127.');}+/**+ * Should a `HOST`-driven bind warn that it is silently dropping a multi-element+ * `server.bind`? `HOST` is a single-address platform-injection variable+ * (Heroku/Railway); when it — and neither `--bind`/`--host` nor `OK_BIND` —+ * drives the bind, it REPLACES the whole file-layer list, halving a dual-stack+ * config with no record the way `OK_BIND` overrides carry. Pure so the boundary+ * (`> 1`, not `>= 1`) is unit-tested independent of the boot path.+ */+export function shouldWarnHostOverridesMultiBind(input: {+ flagBindSet: boolean;+ okBindSet: boolean;+ hostEnvSet: boolean;+ fileBindCount: number;+}): boolean {+ return !input.flagBindSet && !input.okBindSet && input.hostEnvSet && input.fileBindCount > 1;+}+/*** Should this start open the browser? Interactive loopback starts open by* default (suppress with `--no-open-browser`); everything non-interactive or@@ -181,10 +203,14 @@ export function isLoopbackHost(host: string): boolean {* - `--open` (deprecated) then forces open, preserving its pre-flip contract* for scripts that relied on it in non-TTY contexts;* - otherwise: open iff the bind is loopback AND stdout is a TTY (a spawned- * or CI invocation must not pop a browser).+ * or CI invocation must not pop a browser). An EXPLICIT+ * `server.openBrowser: true` / `OK_OPEN_BROWSER=1` (`explicitOn`) lifts+ * the loopback-bind condition — the operator asked by name — but keeps+ * the TTY gate so a container or spawned start still never pops one.*/export function shouldOpenBrowser(input: {openBrowser: boolean;+ explicitOn: boolean;legacyOpen: boolean;host: string;isTTY: boolean;@@ -197,7 +223,7 @@ export function shouldOpenBrowser(input: {if (input.remoteEnabled || input.ephemeral || input.only === 'server') return false;if (!input.servesUi) return false;if (input.legacyOpen) return true;- return isLoopbackHost(input.host) && input.isTTY;+ return (input.explicitOn || isLoopbackHost(input.host)) && input.isTTY;}/**@@ -826,6 +852,18 @@ interface BootStartServerOptions {/** Override idle-shutdown threshold; default 30 min. `null` disables idle* shutdown entirely (`--idle-shutdown off`). Tests use small values. */idleThresholdMs?: number | null;+ /**+ * The fully-layered `server.*` resolution (flags > env > project-local >+ * project > user), threaded to `bootServer` so issued URLs and the+ * exposure interlock consume the same values the CLI resolved. Omitted by+ * legacy callers — `bootServer` then resolves files-only from its config.+ */+ serverRuntime?: ServerRuntimeConfig;+ /**+ * Full bind-address list for multi-listener bind (first entry decides the+ * port; the rest share it). Omitted ⇒ single listener on `host`.+ */+ bind?: readonly string[];/*** Override the process-exit call fired after an idle-shutdown teardown* completes (see `withIdleShutdownProcessExit`). Default `process.exit`.@@ -1246,6 +1284,8 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Boo// CLI-specific opt-insattachUiSibling,idleShutdownMs: idleThresholdMs,+ ...(opts.serverRuntime !== undefined ? { serverRuntime: opts.serverRuntime } : {}),+ ...(opts.bind !== undefined ? { bind: opts.bind } : {}),skipAutoInit: true, // Guard already ran above; no scaffold fn to pass...(attachUiSibling ? { spawnUiSiblingFn } : {}),idleShutdownHandler: (destroyServer) => {@@ -1361,10 +1401,12 @@ interface StartCommandOptions {/** From `--server-url <url>`: where the `--only ui` split-mode UI finds its project server. */serverUrl?: string;/**- * From `--idle-shutdown <dur|off>` (already parsed by `parseIdleShutdownFlag`):- * idle-shutdown threshold in ms, or `null` for `off`. Absent → 30-min default.+ * From `--idle-shutdown <dur|off>`, validated by `parseIdleShutdownFlag`: the+ * duration string (`'off'` | `'90s'` | `'30m'` | …), or absent when the flag+ * is not passed. Converted to ms (null for `'off'`) at the boot boundary via+ * `idleShutdownToMs`, alongside the env/file/derived value.*/- idleShutdown?: number | null;+ idleShutdown?: string;/** From `--mode`: undefined (default → browser) | 'browser' | 'app'. */mode?: StartMode;/**@@ -1528,11 +1570,64 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions));}- // Source-of-truth host + port resolution: CLI flag > env > application- // default. Host lives as a runtime knob only; the port additionally falls- // back to `remote.port` when remote access is enabled (a stable tunnel- // target is part of the remote contract — see coerceRemoteBindHost).- const resolvedHost = resolveHost(opts, process.env as { HOST?: string | undefined });+ // The env config layer (the mechanical OK_* surface + platform PORT):+ // parsed once, leaf-validated, fail-loud on a malformed value with the+ // variable named. Did-you-mean observations surface as warnings.+ let envLayer: EnvConfigLayer;+ try {+ envLayer = resolveEnvConfigLayer(process.env);+ } catch (err) {+ if (err instanceof EnvVarError) {+ console.error(error(err.message));+ process.exit(78);+ }+ throw err;+ }+ for (const diag of envLayer.diagnostics) {+ console.warn(warning(`[config] ${diag.message}`));+ }+ const envConfig = applyConfigOverlay(activeConfig, envLayer.layer) as Config;++ // Bind precedence: --bind / deprecated --host flags > ratified OK_BIND >+ // legacy HOST env > server.bind file layer > loopback default. The resolved+ // LIST is what the derived defaults key off (openBrowser/idleShutdown+ // derive from loopback-only-ness); the listener binds every entry in the+ // list (multi-address bind), each on the same port.+ const okBindSet = envLayer.overrides.some((o) => o.envVar === 'OK_BIND');+ const flagBind =+ opts.bind !== undefined && opts.bind.length > 0+ ? opts.bind+ : opts.host !== undefined+ ? [opts.host]+ : undefined;+ // Empty/whitespace `HOST` reads as unset, matching the env layer's+ // `PORT=''` handling — a platform that exports an empty `HOST` must not+ // produce a `['']` bind list (`''` is non-loopback, so it would trip the+ // exposure interlock with a nonsense "bind includes ()" message).+ const hostEnvRaw = process.env.HOST;+ const hostEnv = hostEnvRaw !== undefined && hostEnvRaw.trim() !== '' ? hostEnvRaw : undefined;+ const envFileRuntime = resolveServerRuntimeConfig(envConfig);+ const requestedBind =+ flagBind ?? (okBindSet || hostEnv === undefined ? [...envFileRuntime.bind] : [hostEnv]);++ // Warn when a `HOST`-driven bind silently drops a multi-element `server.bind`+ // (decision extracted + unit-tested; see shouldWarnHostOverridesMultiBind).+ if (+ shouldWarnHostOverridesMultiBind({+ flagBindSet: flagBind !== undefined,+ okBindSet,+ hostEnvSet: hostEnv !== undefined,+ fileBindCount: envFileRuntime.bind.length,+ })+ ) {+ console.warn(+ warning(+ `[config] HOST=${hostEnv} overrides server.bind — dropping the file-configured addresses (${envFileRuntime.bind.join(', ')}). Use OK_BIND with a space-separated list to keep multiple binds.`,+ ),+ );+ }++ const resolvedHost = requestedBind[0] ?? DEFAULT_SERVER_HOST;const hostCoercion = coerceRemoteBindHost(resolvedHost, remoteEnabled);if (hostCoercion.coerced) {console.warn(@@ -1540,8 +1635,46 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions));}const host = hostCoercion.host;+ // The EFFECTIVE bind list — remote mode collapses to the coerced loopback+ // host (the tunnel is the only ingress there), so the interlock and the+ // ingress policy see what the server actually binds, not the pre-coercion+ // request. Without this, `HOST=0.0.0.0 ok start --remote` coerces to+ // loopback yet still trips ExposureConsentError off the uncoerced list.+ const bindList = remoteEnabled ? [host] : requestedBind;+ const runtime: ServerRuntimeConfig = resolveServerRuntimeConfig(+ applyConfigOverlay(envConfig, { server: { bind: bindList } }) as Config,+ );++ // The consent warning, sibling to the --remote banner above. `allowExternal`+ // is the sanctioned relaxation, but its blast radius is easy to under-read:+ // it exposes not just the editor/collab/API surface but the local-op owner+ // surface (clone, GitHub sign-in, PAT storage, repo spawn) to every external+ // peer, with NO server-side auth. Fire whenever consent is armed AND there is+ // a real exposure vector — a non-loopback bind (direct) or a declared+ // publicUrl (a same-host reverse proxy forwards to a loopback bind). The+ // --remote flow prints its own warning, so skip the duplicate there.+ if (!remoteEnabled && runtime.allowExternal && (!runtime.loopbackOnly || runtime.publicUrl)) {+ const reach = runtime.publicUrl ?? runtime.bind.join(', ');+ console.warn(+ warning(+ [+ '',+ '⚠ EXTERNAL ACCESS ENABLED (server.allowExternal) — no server-side authentication.',+ ` This server is reachable beyond this machine (${reach}). Anyone who can`,+ ' reach it has FULL control of this knowledge base — sync, publishing, GitHub',+ ' credentials, and local operations (clone, sign-in, repo spawn).',+ ' Restrict who can reach it at the edge: a Tailscale ACL, a reverse proxy with',+ ' auth (Cloudflare Access, oauth2-proxy), or a firewall.',+ '',+ ].join('\n'),+ ),+ );+ }+const portFromCli = opts.port !== undefined ? Number(opts.port) : undefined;- const portFromEnv = process.env.PORT ? Number(process.env.PORT) : undefined;+ const portFromEnv = envLayer.overrides.find((o) => o.envVar === 'PORT')?.value as+ | number+ | undefined;const requestedUiPort = opts.uiPort !== undefined ? Number(opts.uiPort) : undefined;// When `--ui-port` is set, the preview pane's `PORT` env is the UI sibling's// intended port, NOT the collab server's — honoring it for the collab port@@ -1554,14 +1687,23 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)// A stable port matters in remote mode because the tailscale serve/funnel// mapping names a fixed target port — a kernel-assigned ephemeral port would// break the tunnel on every restart.+ // File-layer ports, split by consumer:+ // - `remotePort` follows the resolver's `server.port ?? remote.port` alias+ // — remote mode wants the stable tunnel-target port from either key.+ // - `localPort` is the SUCCESSOR key ONLY. A plain local start must not+ // inherit a dormant `remote.port` (set long ago for tunnel use); doing so+ // pins every local boot to that fixed port instead of a free dynamic one,+ // and two projects both carrying `remote.port` could never run at once.+ const remotePort = resolveServerRuntimeConfig(activeConfig).port;+ const localPort = activeConfig.server?.port;if (remoteEnabled && portFromCli === undefined && portFromEnv !== undefined) {console.warn(- `remote access is enabled — ignoring env PORT=${process.env.PORT}; the tunnel's port mapping targets the stable remote port (${activeConfig.remote?.port ?? DEFAULT_REMOTE_PORT}). Pass --port to override deliberately.`,+ `remote access is enabled — ignoring env PORT=${process.env.PORT}; the tunnel's port mapping targets the stable remote port (${remotePort ?? DEFAULT_REMOTE_PORT}). Pass --port to override deliberately.`,);}const port =resolveCollabPort(portFromCli, portFromEnv, requestedUiPort, remoteEnabled) ??- (remoteEnabled ? (activeConfig.remote?.port ?? DEFAULT_REMOTE_PORT) : undefined);+ (remoteEnabled ? (remotePort ?? DEFAULT_REMOTE_PORT) : localPort);// Fast path: when `--ui-port` is set (the worktree-preview recipe), a// live collab server already in this folder means we must NOT boot a second@@ -1610,6 +1752,9 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)cwd,host,port,+ // Full bind list for the multi-listener bind — already collapsed to the+ // coerced loopback host in remote mode (see `bindList` above).+ bind: bindList,...(requestedUiPort !== undefined ? { uiPort: requestedUiPort } : {}),...(opts.serveContentAssets !== undefined? { serveContentAssets: opts.serveContentAssets }@@ -1619,7 +1764,14 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)// bundle is missing — a spawned `ok ui` would be serving the same// missing bundle, and the warning above already promised API/MCP-only....(opts.only === 'server' || shell.missingBundle ? { skipUiAutoSpawn: true } : {}),- ...(opts.idleShutdown !== undefined ? { idleThresholdMs: opts.idleShutdown } : {}),+ // Flag > env/file/derived, resolved uniformly: both the flag value and+ // the resolver's idleShutdown are duration strings ('off' | '90s' | …) —+ // the resolver's covers OK_IDLE_SHUTDOWN, the config leaf, and the+ // bind-derived default ('30m' loopback-only, 'off' exposed). Converted to+ // ms (null for 'off') at this single boundary. The flag stays a string+ // through Commander on purpose — see parseIdleShutdownFlag.+ idleThresholdMs: idleShutdownToMs(opts.idleShutdown ?? runtime.idleShutdown),+ serverRuntime: runtime,...(opts.singleFile ? { singleFile: opts.singleFile } : {}),...(opts.projectDir ? { projectDir: opts.projectDir } : {}),...(remoteEnabled ? { enableRemote: true } : {}),@@ -1650,6 +1802,14 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)process.exit(78);}+ // Exposure without consent (non-loopback bind or publicUrl set while+ // server.allowExternal is off) — the interlock's message IS the one-line+ // fix. EX_CONFIG, same contract as RemoteConfigError.+ if (err instanceof serverModule.ExposureConsentError) {+ console.error(error(err.message));+ process.exit(78);+ }+// Single-file open target was rejected (missing / not a file / not// markdown). The thrown error carries a user-facing one-liner — surface it// cleanly instead of a stack trace, matching `ok <file>`'s own handling.@@ -1837,7 +1997,10 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)// banner URL is the full editor (suppress with --no-open-browser; the// deprecated --open force-opens). Decision table: `shouldOpenBrowser`.const openDecision = shouldOpenBrowser({- openBrowser: opts.openBrowser !== false,+ // Flag suppression wins; otherwise the resolver's openBrowser covers+ // OK_OPEN_BROWSER, the config leaf, and the bind-derived default.+ openBrowser: opts.openBrowser !== false && runtime.openBrowser,+ explicitOn: opts.openBrowser !== false && envConfig.server?.openBrowser === true,legacyOpen: opts.open === true,host,isTTY: process.stdout.isTTY === true,@@ -2071,16 +2234,6 @@ export function startCommand(getConfig: () => Config): Command {.action(async (opts: StartCommandOptions) => {const config = getConfig();- // `--bind` is declared repeatable because the config surface reserves a- // bind LIST, but multi-bind isn't implemented yet — reject loudly- // rather than silently binding only the first address.- if (opts.bind !== undefined && opts.bind.length > 1) {- process.stderr.write(- 'error: multiple --bind addresses are not supported yet — pass a single address\n',- );- process.exit(2);- }-// `--server-url` only means something to the --only ui proxy.if (opts.serverUrl !== undefined && opts.only !== 'ui') {process.stderr.write("error: option '--server-url' requires '--only ui'\n");diff --git a/packages/cli/src/config/loader.test.ts b/packages/cli/src/config/loader.test.tsindex e83a87a9f..e4f847a31 100644--- a/packages/cli/src/config/loader.test.ts+++ b/packages/cli/src/config/loader.test.ts@@ -47,6 +47,13 @@ function writeWorkspaceConfig(yaml: string) {writeFileSync(resolve(configDir, 'config.yml'), yaml, 'utf-8');}+/** Helper: write a project-local .ok/local/config.yml inside testDir */+function writeLocalConfig(yaml: string) {+ const localDir = resolve(testDir, OK_DIR, 'local');+ mkdirSync(localDir, { recursive: true });+ writeFileSync(resolve(localDir, 'config.yml'), yaml, 'utf-8');+}+function writeWorkspaceConfigAt(dir: string, yaml: string) {const configDir = resolve(dir, OK_DIR);mkdirSync(configDir, { recursive: true });@@ -184,7 +191,11 @@ appearance:const { config } = loadConfig(testDir);expect(config.content.dir).toBe('docs');- expect(config.appearance.theme).toBe('dark');+ // Posture flip (scope-aware loader): appearance.theme is a USER-scoped+ // leaf, so a project-file value no longer reaches the merged view — a+ // committed theme must not force one collaborator's preference on+ // everyone. Previously the scope-blind deep merge let it win.+ expect(config.appearance.theme).toBeUndefined();});test('content.include in project config is stripped with .okignore redirect; content.dir survives', () => {@@ -262,12 +273,14 @@ folders:expect(folders?.redirect).toContain('edit({ folder');});- test('appearance.editorModeDefault in project config is stripped; appearance.theme survives', () => {+ test('appearance.editorModeDefault in project config is stripped; sibling parses', () => {// Also previously silent — never read by the engine.writeWorkspaceConfig('appearance:\n theme: dark\n editorModeDefault: source\n');const { config, diagnostics } = loadConfig(testDir);- // Sibling under the same parent keeps its on-disk value.- expect(config.appearance.theme).toBe('dark');+ // Posture flip (scope-aware loader): the live sibling still PARSES (the+ // strip must not take it down), but appearance.theme is a USER-scoped+ // leaf, so the project-file value no longer reaches the merged view.+ expect(config.appearance.theme).toBeUndefined();const mode = removedKeys(diagnostics).find((r) => r.dotted === 'appearance.editorModeDefault');expect(mode).toBeDefined();expect(mode?.redirect).toContain('WYSIWYG');@@ -308,11 +321,25 @@ folders:// ── Validation ──────────────────────────────────────────────────────- test('appearance.theme outside the enum throws', () => {- writeWorkspaceConfig('appearance:\n theme: midnight\n');+ test('an invalid project-scoped value throws', () => {+ // server.port is project-scoped and range-checked (1–65535); an+ // out-of-range value survives the scope-aware merge and fails the single+ // merged parse.+ writeWorkspaceConfig('server:\n port: 99999999\n');expect(() => loadConfig(testDir)).toThrow('Invalid configuration');});+ test('a mis-scoped user-scoped value in the project file is ignored, not thrown', () => {+ // Raw-merge-then-parse-once trade: the scope-aware merge drops a+ // user-scoped leaf (appearance.theme) set in the project file BEFORE the+ // single merged parse, so an invalid value there is silently ignored+ // rather than reported — errors surface only for values that reach the+ // merged view. (A project cannot set a user-scoped key anyway.)+ writeWorkspaceConfig('appearance:\n theme: midnight\n');+ expect(() => loadConfig(testDir)).not.toThrow();+ expect(loadConfig(testDir).config.appearance.theme).toBeUndefined();+ });+// ── Edge cases ──────────────────────────────────────────────────────test('unknown top-level keys are silently ignored (forward-compat)', () => {@@ -340,11 +367,11 @@ folders:// ── Source-located errors ────────────────────────────test('schema-invalid project config emits file:line:col in error message', () => {- // appearance.theme is a string enum — typing it as a non-member value- // fails Zod validation. The loader uses parseDocument + locateIssue to- // map the issue back to source position.- const yaml = `appearance:- theme: midnight+ // server.port is project-scoped, so an out-of-range value survives the+ // scope-aware merge and fails the single merged parse; the loader uses+ // parseDocument + locateIssue to map the issue back to source position.+ const yaml = `server:+ port: 99999999`;writeWorkspaceConfig(yaml);let caught: Error | undefined;@@ -356,14 +383,14 @@ folders:expect(caught).toBeDefined();const expectedPath = resolve(testDir, OK_DIR, 'config.yml');// The expected literal: <abs-path>:<line>:<col> — must be `2:` because- // `theme: midnight` lives on line 2 of the fixture above.+ // `port: 99999999` lives on line 2 of the fixture above.expect(caught?.message).toContain(`${expectedPath}:2:`);// Error message also includes the path-message line and a snippet.- expect(caught?.message).toContain('appearance.theme');+ expect(caught?.message).toContain('server.port');});test('source-located error renders code snippet with caret marker', () => {- writeWorkspaceConfig('appearance:\n theme: midnight\n');+ writeWorkspaceConfig('server:\n port: 99999999\n');let caught: Error | undefined;try {loadConfig(testDir);@@ -537,3 +564,80 @@ describe('createProjectConfigResolver', () => {expect(loadCalls).toBe(2);});});++describe('loadConfig — scope-aware layering (project-local)', () => {+ test('project-local layer is read and lands in sources', () => {+ writeLocalConfig('server:\n allowExternal: true\n');+ const { config, sources } = loadConfig(testDir);+ expect(config.server.allowExternal).toBe(true);+ expect(sources).toContain(resolve(testDir, OK_DIR, 'local', 'config.yml'));+ });++ test('a committed server.allowExternal: true never arms exposure (clone-leak guarantee)', () => {+ // allowExternal is a PROJECT-LOCAL leaf: consent never travels via git,+ // clone, or share. mergeLayered's project-local scope rule skips the+ // committed project layer, so a committed value resolves to the schema+ // default (false) — the leak the scope-blind deep merge used to allow.+ writeWorkspaceConfig('server:\n allowExternal: true\n');+ const { config } = loadConfig(testDir);+ expect(config.server.allowExternal).toBe(false);+ });++ test('committed openBrowser / idleShutdown (project-local, no schema default) are also inert', () => {+ // These project-local leaves have NO Zod default (they derive at resolve+ // time), so the old "parsed local default wins" guard didn't protect them+ // — a committed value used to travel via clone. The scope-skip closes that+ // regardless of whether the leaf has a default: committed values are+ // dropped, leaving the leaf undefined for the resolver to derive.+ writeWorkspaceConfig('server:\n openBrowser: true\n idleShutdown: off\n');+ const { config } = loadConfig(testDir);+ expect(config.server.openBrowser).toBeUndefined();+ expect(config.server.idleShutdown).toBeUndefined();+ });++ test('an explicit user-global value survives an empty project file (precedence, not clobber)', () => {+ // Regression pin for the precedence bug: telemetry.localSink.enabled is+ // project-scoped with a schema default of true. A user who disables it in+ // ~/.ok/global.yml, in a project that never mentions the key, must keep+ // false — the old per-layer parse filled the project layer's default true+ // and clobbered the user value. Raw layers leave the project leaf+ // undefined, so the project-scope rule falls back to the user's false.+ const okDir = resolve(fakeHome, OK_DIR);+ mkdirSync(okDir, { recursive: true });+ writeFileSync(+ resolve(okDir, 'global.yml'),+ 'telemetry:\n localSink:\n enabled: false\n',+ 'utf-8',+ );+ const { config } = loadConfig(testDir);+ expect(config.telemetry.localSink.enabled).toBe(false);+ });++ test('project-local wins over project for a project-local leaf it sets', () => {+ writeWorkspaceConfig('server:\n port: 8080\n');+ writeLocalConfig('server:\n openBrowser: false\n');+ const { config } = loadConfig(testDir);+ // Project-scoped leaf from the project layer…+ expect(config.server.port).toBe(8080);+ // …and the project-local leaf from the local layer, in one merged view.+ expect(config.server.openBrowser).toBe(false);+ });++ test('project layer still owns project-scoped server keys', () => {+ writeWorkspaceConfig('server:\n bind:\n - 127.0.0.1\n - 100.64.0.7\n');+ const { config } = loadConfig(testDir);+ expect(config.server.bind).toEqual(['127.0.0.1', '100.64.0.7']);+ });++ test('schema-invalid project-local file throws loud with the file named', () => {+ writeLocalConfig('server:\n openBrowser: "sometimes"\n');+ expect(() => loadConfig(testDir)).toThrow(/openBrowser/);+ });++ test('removed keys in the project-local file strip-and-continue', () => {+ writeLocalConfig('server:\n host: 0.0.0.0\n openBrowser: false\n');+ const { config, diagnostics } = loadConfig(testDir);+ expect(config.server.openBrowser).toBe(false);+ expect(removedKeys(diagnostics).some((k) => k.dotted === 'server.host')).toBe(true);+ });+});diff --git a/packages/cli/src/config/loader.ts b/packages/cli/src/config/loader.tsindex 84883354b..78d16b178 100644--- a/packages/cli/src/config/loader.ts+++ b/packages/cli/src/config/loader.ts@@ -2,11 +2,16 @@* Hierarchical YAML config loader.** Priority (lowest → highest):- * Zod defaults → ~/.ok/global.yml → ./.ok/config.yml+ * Zod defaults → ~/.ok/global.yml → ./.ok/config.yml → ./.ok/local/config.yml** ENV and CLI flag overrides are applied in cli.ts after loading.*- * Deep merge: project leaf values override user leaf values.+ * The three file layers combine through the scope-aware `mergeLayered` (each+ * layer schema-parsed on its own first): a leaf's registered scope decides+ * which layer may set it, so a committed project-file value for a+ * project-local leaf — the load-bearing case is `server.allowExternal: true`+ * arriving via clone — can never win over the local layer's parsed default.+ * A scope-blind deep merge here previously let any layer set any leaf.* Arrays are replaced, not concatenated.** Errors are emitted with source positions via yaml@2's `parseDocument` —@@ -16,14 +21,14 @@* `.ok/config.yml` so the ancestor-walk that detects an OK project can't* treat the user's home directory as a project root.*- * Both layers strip removed keys and continue: a key the engine no longer+ * Every layer strips removed keys and continues: a key the engine no longer* reads is deleted from the parsed value and reported on* `LoadConfigResult.diagnostics`, never blocking startup. Genuine corruption* still fails the way it did before: the user-global file is sidelined to* `<path>.invalid-<ISO-timestamp>` and replaced with schema defaults (via- * `readConfigSafely`) so OK can still boot, and a schema-invalid project file- * throws loud — a project error is user-fixable in place and failing fast- * helps the user notice.+ * `readConfigSafely`) so OK can still boot, and a schema-invalid project or+ * project-local file throws loud — both are user-fixable in place and+ * failing fast helps the user notice.*/import { existsSync, readFileSync } from 'node:fs';import { resolve } from 'node:path';@@ -34,6 +39,7 @@ import {detectRemovedKeys,humanFormat,locateIssue,+ mergeLayered,stripRemovedKeys,} from '@inkeep/open-knowledge-core';import { readConfigSafely, resolveConfigPath } from '@inkeep/open-knowledge-core/server';@@ -64,27 +70,6 @@ export interface LoadConfigResult {/** Short TTL for per-cwd config resolution in long-lived MCP sessions. */const DEFAULT_CONFIG_CACHE_MS = 1000;-/**- * Deep merge two objects. Leaf values in `override` replace `base`.- * Arrays are replaced, not concatenated.- */-function deepMerge(- base: Record<string, unknown>,- override: Record<string, unknown>,-): Record<string, unknown> {- const result = { ...base };- for (const key of Object.keys(override)) {- const baseVal = base[key];- const overrideVal = override[key];- if (isObject(overrideVal) && isObject(baseVal)) {- result[key] = deepMerge(baseVal, overrideVal);- } else if (overrideVal !== undefined) {- result[key] = overrideVal;- }- }- return result;-}-interface LoadedYamlFile {/** Parsed JS object (or null if the file is empty / comments-only / missing). */value: Record<string, unknown> | null;@@ -197,58 +182,66 @@ export function loadConfig(cwd?: string): LoadConfigResult {// Layer 1: user-global config — go through readConfigSafely so removed keys// are stripped-and-reported and a genuinely broken file is sidelined; either- // way we boot instead of hanging the user.+ // way we boot instead of hanging the user. Its return value is already a+ // schema-parsed Config (defaults applied) — the per-layer shape+ // mergeLayered's scope rules operate on.const userConfigPath = resolveConfigPath('user', workingDir);const userResult = readConfigSafely({ absPath: userConfigPath });diagnostics.push(...userResult.diagnostics);if (!userResult.valid && userResult.sidelinedTo !== undefined) {sidelined.push({ from: userConfigPath, to: userResult.sidelinedTo });}- let merged: Record<string, unknown> = {};if (userResult.valid && userResult.source !== undefined) {- // Re-emit through the JSON projection so deepMerge stays uniform.- merged = deepMerge(merged, userResult.value as unknown as Record<string, unknown>);sources.push(userConfigPath);- } else if (!userResult.valid) {- // readConfigSafely already logged + sidelined; we treat this as "user- // contributed nothing" and proceed with defaults at this layer.}- // Layer 2: project config. Strip removed keys and continue — a dead key must- // not brick startup — but a schema violation still throws loud, because a- // project schema error is user-fixable in place.- const projectConfigPath = resolve(workingDir, OK_DIR, CONFIG_FILENAME);- const projectFile = loadYamlFile(projectConfigPath);- // A project file that could not be read or parsed degrades to defaults, same- // as before — but it now says so. Without this the whole merged config falls- // back to defaults, which always validate, so every reporting surface built- // on `diagnostics` would call a broken file clean.- if (projectFile.diagnostic !== undefined) {- diagnostics.push(projectFile.diagnostic);- }- if (projectFile.value !== null) {+ // Layers 2 + 3: project (committed) and project-local (gitignored,+ // per-machine). Read RAW — removed keys stripped and reported, but NOT+ // schema-parsed. Leaving an unset leaf `undefined` (rather than filling its+ // schema default per layer) is load-bearing two ways:+ // 1. an empty/missing project file no longer clobbers an explicit+ // user-global value with a filled default (the precedence bug);+ // 2. `mergeLayered`'s project-local scope rule skips the committed project+ // layer, so a committed `server.allowExternal` (or any project-local+ // key) resolves to its schema default — never the cloned value.+ // A file that could not be read/parsed degrades to `{}` but says so via+ // `diagnostics`.+ const loadRawLayer = (filePath: string): Record<string, unknown> => {+ const file = loadYamlFile(filePath);+ if (file.diagnostic !== undefined) {+ diagnostics.push(file.diagnostic);+ }+ if (file.value === null) return {};const removedKeyDiagnostics = detectRemovedKeys({- value: projectFile.value,- file: projectFile.path,- source: projectFile.source,- doc: projectFile.doc,+ value: file.value,+ file: file.path,+ source: file.source,+ doc: file.doc,});diagnostics.push(...removedKeyDiagnostics);- const cleaned =- removedKeyDiagnostics.length > 0 ? stripRemovedKeys(projectFile.value) : projectFile.value;- merged = deepMerge(merged, cleaned);- sources.push(projectConfigPath);- }+ sources.push(filePath);+ return removedKeyDiagnostics.length > 0 ? stripRemovedKeys(file.value) : file.value;+ };++ const projectPath = resolve(workingDir, OK_DIR, CONFIG_FILENAME);+ const projectRaw = loadRawLayer(projectPath);+ const localRaw = loadRawLayer(resolveConfigPath('project-local', workingDir));- // Validate the merged result with Zod. Removed keys were already stripped, so- // a failure here is a genuine schema violation — throw source-located.+ // Scope-aware merge over the raw layers, then ONE parse fills defaults for+ // genuinely-unset leaves. DELIBERATE TRADE (do not "fix" back to per-layer+ // parsing — that reintroduces the precedence + project-local-leak bugs): a+ // schema violation now surfaces at this merged parse, so a bad value in the+ // project or project-local file reports at the merged level rather than+ // `file:line`. Source location is best-effort attributed to the project+ // file when the offending path resolves there.+ const merged = mergeLayered(userResult.value as Record<string, unknown>, projectRaw, localRaw);const result = ConfigSchema.safeParse(merged);if (!result.success) {+ const projectFile = loadYamlFile(projectPath);const issues = annotateIssuesWithSource(result.error.issues, projectFile);const error: ConfigValidationError = { code: 'SCHEMA_INVALID', issues };throw new Error(humanFormat(error));}-return { config: result.data, sources, diagnostics, sidelined };}diff --git a/packages/core/src/config/env-layer.test.ts b/packages/core/src/config/env-layer.test.tsnew file mode 100644index 000000000..566b8bf4a--- /dev/null+++ b/packages/core/src/config/env-layer.test.ts@@ -0,0 +1,143 @@+import { describe, expect, it } from 'vitest';+import {+ EnvVarError,+ listConfigLeafPaths,+ mechanicalEnvName,+ mechanicalEnvNameTable,+ RECOGNIZED_ENV_VARS,+ resolveEnvConfigLayer,+} from './env-layer.ts';++describe('mechanical naming rule', () => {+ it('server-section leaves map to bare OK_<LEAF>', () => {+ expect(mechanicalEnvName(['server', 'bind'])).toBe('OK_BIND');+ expect(mechanicalEnvName(['server', 'publicUrl'])).toBe('OK_PUBLIC_URL');+ expect(mechanicalEnvName(['server', 'allowExternal'])).toBe('OK_ALLOW_EXTERNAL');+ expect(mechanicalEnvName(['server', 'idleShutdown'])).toBe('OK_IDLE_SHUTDOWN');+ expect(mechanicalEnvName(['server', 'openBrowser'])).toBe('OK_OPEN_BROWSER');+ });++ it('other sections map to OK_<SECTION>_<LEAF>', () => {+ expect(mechanicalEnvName(['content', 'dir'])).toBe('OK_CONTENT_DIR');+ expect(mechanicalEnvName(['autoSync', 'mode'])).toBe('OK_AUTO_SYNC_MODE');+ });++ it('the full table covers every config leaf', () => {+ const table = mechanicalEnvNameTable();+ expect(table.get('OK_CONTENT_DIR')).toEqual(['content', 'dir']);+ expect(table.get('OK_AUTO_SYNC_MODE')).toEqual(['autoSync', 'mode']);+ // Every enumerated leaf appears exactly once (no name collisions).+ expect(table.size).toBe(listConfigLeafPaths().length);+ });+});++describe('recognized surface pin', () => {+ // Name-lock guard: env names lock at the release that first ships them.+ // Widening this set is a deliberate ratification, never a drive-by — a+ // failure here means the shipped env surface changed.+ it('is exactly the ratified Table 2 set', () => {+ expect(new Map(RECOGNIZED_ENV_VARS)).toEqual(+ new Map([+ ['PORT', ['server', 'port']],+ ['OK_BIND', ['server', 'bind']],+ ['OK_PUBLIC_URL', ['server', 'publicUrl']],+ ['OK_ALLOW_EXTERNAL', ['server', 'allowExternal']],+ ['OK_OPEN_BROWSER', ['server', 'openBrowser']],+ ['OK_IDLE_SHUTDOWN', ['server', 'idleShutdown']],+ ]),+ );+ });+});++describe('resolveEnvConfigLayer', () => {+ it('parses the full ratified surface into a deep-partial layer', () => {+ const { layer, overrides, diagnostics } = resolveEnvConfigLayer({+ PORT: '8080',+ OK_BIND: '127.0.0.1 100.64.0.7',+ OK_PUBLIC_URL: 'https://kb.example.com',+ OK_ALLOW_EXTERNAL: '1',+ OK_OPEN_BROWSER: 'false',+ OK_IDLE_SHUTDOWN: 'off',+ });+ expect(layer).toEqual({+ server: {+ port: 8080,+ bind: ['127.0.0.1', '100.64.0.7'],+ publicUrl: 'https://kb.example.com',+ allowExternal: true,+ openBrowser: false,+ idleShutdown: 'off',+ },+ });+ expect(overrides).toHaveLength(6);+ expect(diagnostics).toEqual([]);+ });++ it('ignores unset and empty values (PORT="" platform quirk)', () => {+ const { overrides } = resolveEnvConfigLayer({ PORT: '', OK_BIND: ' ' });+ expect(overrides).toEqual([]);+ });++ it('booleans accept exactly 1/0/true/false and are never presence-checked', () => {+ expect(resolveEnvConfigLayer({ OK_ALLOW_EXTERNAL: 'true' }).layer).toEqual({+ server: { allowExternal: true },+ });+ expect(resolveEnvConfigLayer({ OK_ALLOW_EXTERNAL: '0' }).layer).toEqual({+ server: { allowExternal: false },+ });+ expect(() => resolveEnvConfigLayer({ OK_ALLOW_EXTERNAL: 'yes' })).toThrow(EnvVarError);+ expect(() => resolveEnvConfigLayer({ OK_OPEN_BROWSER: 'on' })).toThrow(/OK_OPEN_BROWSER/);+ });++ it('rejects malformed values with the env var named', () => {+ expect(() => resolveEnvConfigLayer({ PORT: 'dynamic' })).toThrow(/^PORT:/);+ expect(() => resolveEnvConfigLayer({ PORT: '70000' })).toThrow(EnvVarError);+ expect(() => resolveEnvConfigLayer({ OK_PUBLIC_URL: 'not a url' })).toThrow(/OK_PUBLIC_URL/);+ expect(() => resolveEnvConfigLayer({ OK_PUBLIC_URL: 'ftp://kb.example.com' })).toThrow(+ EnvVarError,+ );+ expect(() => resolveEnvConfigLayer({ OK_IDLE_SHUTDOWN: '30x' })).toThrow(/OK_IDLE_SHUTDOWN/);+ });++ it('accepts http publicUrl (tailnet/LAN use) and duration idleShutdown', () => {+ const { layer } = resolveEnvConfigLayer({+ OK_PUBLIC_URL: 'http://laptop.tail:55222',+ OK_IDLE_SHUTDOWN: '45m',+ });+ expect(layer).toEqual({+ server: { publicUrl: 'http://laptop.tail:55222', idleShutdown: '45m' },+ });+ });++ it('warns on OK_PORT (the ratified spelling is unprefixed PORT)', () => {+ const { diagnostics, overrides } = resolveEnvConfigLayer({ OK_PORT: '8080' });+ expect(overrides).toEqual([]);+ expect(diagnostics).toHaveLength(1);+ expect(diagnostics[0]?.message).toContain('unprefixed PORT');+ });++ it('warns when an unknown var mechanically maps to a non-env-configurable leaf', () => {+ const { diagnostics } = resolveEnvConfigLayer({ OK_AUTO_SYNC_MODE: 'commit' });+ expect(diagnostics).toHaveLength(1);+ expect(diagnostics[0]?.message).toContain('autoSync.mode');+ expect(diagnostics[0]?.message).toContain('not env-configurable');+ });++ it('warns did-you-mean on a near-miss of a recognized name', () => {+ const { diagnostics } = resolveEnvConfigLayer({ OK_BINDD: '0.0.0.0' });+ expect(diagnostics).toHaveLength(1);+ expect(diagnostics[0]?.message).toContain('OK_BIND');+ });++ it('stays silent on legitimate operational OK_* vars and non-OK vars', () => {+ const { diagnostics, overrides } = resolveEnvConfigLayer({+ OK_LOCK_KIND: 'mcp-spawned',+ OK_RECLAIM_DISABLE: '1',+ OK_DESTROY_STEP_TIMEOUT_MS: '9000',+ HOME: '/home/u',+ HOST: '0.0.0.0',+ });+ expect(overrides).toEqual([]);+ expect(diagnostics).toEqual([]);+ });+});diff --git a/packages/core/src/config/env-layer.ts b/packages/core/src/config/env-layer.tsnew file mode 100644index 000000000..9fe11b56f--- /dev/null+++ b/packages/core/src/config/env-layer.ts@@ -0,0 +1,289 @@+/**+ * Environment-variable config layer — the mechanical `OK_*` mapping rule.+ *+ * Naming rule (the only one there is, so no per-key naming decisions ever+ * again): a leaf under the `server.` section maps to bare `OK_<LEAF>`+ * (`server.publicUrl` → `OK_PUBLIC_URL`); every other section maps to+ * `OK_<SECTION>_<LEAF>` (`autoSync.mode` → `OK_AUTO_SYNC_MODE`). camelCase+ * segments render as underscore-separated uppercase. One pinned exception:+ * `server.port` is read from unprefixed `PORT` — the platform-injection+ * contract (Heroku/Railway/Cloud Run) — never `OK_PORT`.+ *+ * RECOGNITION IS GATED to the ratified set below. Env names lock the moment a+ * release ships them and betas cut per merge, so recognizing every config+ * leaf mechanically would irreversibly lock an env name per leaf in one+ * unreviewed shot. The machinery underneath (name table, leaf-typed parsing)+ * is generic; widening the surface is a one-line allowlist addition once a+ * name is ratified.+ *+ * Precedence: flags > env > project-local > project > user > defaults —+ * callers merge the returned layer above the file-merged config and let+ * explicit CLI flags override the result. Values parse by the leaf's own+ * schema type (boolean: exactly `1`/`0`/`true`/`false`, never+ * presence-checked; lists: space-separated, replace never merge; numbers:+ * integers) and then validate against the leaf schema itself, so a bad value+ * fails loud at boot naming the env var — not later as an opaque config+ * error. An empty/whitespace value reads as unset (the `PORT=''` platform+ * quirk), never as an error.+ *+ * Unrecognized `OK_*` vars are mostly legitimate operational toggles+ * (`OK_LOCK_KIND`, `OK_RECLAIM_DISABLE`, …), so diagnostics are deliberately+ * conservative: warn only on an exact mechanical match to a config leaf that+ * is not env-configurable, or a near-miss (edit distance ≤ 2) of a recognized+ * name. Everything else stays silent.+ */++import type { z } from 'zod';+import { ConfigSchema } from './schema.ts';+import { resolveLeafSchema } from './schema-leaf.ts';++/** A single env-var override, parsed and leaf-validated. */+export interface EnvOverride {+ /** Config path the value applies to, e.g. `['server', 'bind']`. */+ path: readonly string[];+ /** The environment variable the value came from. */+ envVar: string;+ /** Parsed value, already validated against the leaf schema. */+ value: unknown;+}++/** Non-fatal env-layer observation (unknown-var did-you-mean, etc.). */+export interface EnvDiagnostic {+ envVar: string;+ message: string;+}++export interface EnvConfigLayer {+ overrides: EnvOverride[];+ /**+ * Deep-partial config assembled from `overrides` — merge it above the+ * project-local file layer. Lists and scalars replace; nothing merges.+ */+ layer: Record<string, unknown>;+ diagnostics: EnvDiagnostic[];+}++/** Fatal env-var parse/validation failure — boot error with a one-line fix. */+export class EnvVarError extends Error {+ readonly envVar: string;+ constructor(envVar: string, message: string) {+ super(`${envVar}: ${message}`);+ this.name = 'EnvVarError';+ this.envVar = envVar;+ }+}++/**+ * The ratified env surface (config-surface decision, Tables 1–2). Key: env+ * var; value: config path. `server.trustedProxies` is deferred with its key;+ * `auth.*` is deferred entirely — neither appears here until ratified.+ */+export const RECOGNIZED_ENV_VARS: ReadonlyMap<string, readonly string[]> = new Map([+ ['PORT', ['server', 'port']],+ ['OK_BIND', ['server', 'bind']],+ ['OK_PUBLIC_URL', ['server', 'publicUrl']],+ ['OK_ALLOW_EXTERNAL', ['server', 'allowExternal']],+ ['OK_OPEN_BROWSER', ['server', 'openBrowser']],+ ['OK_IDLE_SHUTDOWN', ['server', 'idleShutdown']],+]);++function camelToScreamingSnake(segment: string): string {+ return segment.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();+}++/** The mechanical naming rule. Exported for the name-table pin test. */+export function mechanicalEnvName(path: readonly string[]): string {+ const segments = path[0] === 'server' ? path.slice(1) : path;+ return `OK_${segments.map(camelToScreamingSnake).join('_')}`;+}++type AnyZ = z.ZodType<unknown>;++function unwrapLeaf(schema: unknown): unknown {+ let cur: unknown = schema;+ for (let depth = 0; depth < 16; depth++) {+ const def = (cur as { _zod?: { def?: { type?: string; innerType?: unknown } } })?._zod?.def;+ if (def === undefined) return cur;+ if (def.type !== 'default' && def.type !== 'optional' && def.type !== 'nullable') return cur;+ cur = def.innerType;+ }+ return cur;+}++function leafTypeTag(schema: unknown): string | undefined {+ return (unwrapLeaf(schema) as { _zod?: { def?: { type?: string } } })?._zod?.def?.type;+}++/**+ * Enumerate every leaf path in a ZodObject tree. Objects recurse; anything+ * else (scalars, arrays, records, unions) is a leaf. Wrapper layers+ * (`.default()` / `.optional()` / `.nullable()`) are transparent.+ */+export function listConfigLeafPaths(root: AnyZ = ConfigSchema): string[][] {+ const out: string[][] = [];+ const visit = (schema: unknown, path: string[]): void => {+ const unwrapped = unwrapLeaf(schema);+ const shape = (unwrapped as { _zod?: { def?: { shape?: Record<string, unknown> } } })?._zod?.def+ ?.shape;+ if (shape === undefined) {+ if (path.length > 0) out.push(path);+ return;+ }+ for (const [key, child] of Object.entries(shape)) visit(child, [...path, key]);+ };+ visit(root, []);+ return out;+}++/**+ * The full mechanical name table over every config leaf — reverse-lookup+ * source for diagnostics ("OK_AUTO_SYNC_MODE maps to autoSync.mode, which is+ * not env-configurable") and the surface a future ratification widens into.+ */+export function mechanicalEnvNameTable(): ReadonlyMap<string, readonly string[]> {+ const table = new Map<string, readonly string[]>();+ for (const path of listConfigLeafPaths()) table.set(mechanicalEnvName(path), path);+ return table;+}++function parseByLeafType(envVar: string, raw: string, leaf: AnyZ): unknown {+ switch (leafTypeTag(leaf)) {+ case 'boolean': {+ if (raw === '1' || raw === 'true') return true;+ if (raw === '0' || raw === 'false') return false;+ throw new EnvVarError(+ envVar,+ `expected a boolean (1/0/true/false), got ${JSON.stringify(raw)}`,+ );+ }+ case 'number': {+ const n = Number(raw);+ if (!Number.isFinite(n)) {+ throw new EnvVarError(envVar, `expected a number, got ${JSON.stringify(raw)}`);+ }+ return n;+ }+ case 'array':+ // Space-separated (Redis-style bind lists). Lists replace, never merge.+ return raw.split(/\s+/).filter((entry) => entry !== '');+ default:+ return raw;+ }+}++function levenshtein(a: string, b: string): number {+ const prev = new Array<number>(b.length + 1);+ for (let j = 0; j <= b.length; j++) prev[j] = j;+ for (let i = 1; i <= a.length; i++) {+ let diag = prev[0] as number;+ prev[0] = i;+ for (let j = 1; j <= b.length; j++) {+ const next = Math.min(+ (prev[j] as number) + 1,+ (prev[j - 1] as number) + 1,+ diag + (a[i - 1] === b[j - 1] ? 0 : 1),+ );+ diag = prev[j] as number;+ prev[j] = next;+ }+ }+ return prev[b.length] as number;+}++function diagnoseUnknownOkVar(+ envVar: string,+ mechanicalTable: ReadonlyMap<string, readonly string[]>,+): EnvDiagnostic | null {+ // `server.port`'s mechanical spelling — the ratified name is unprefixed PORT.+ if (envVar === 'OK_PORT') {+ return { envVar, message: 'OK_PORT is not read — the port variable is unprefixed PORT.' };+ }+ const mapped = mechanicalTable.get(envVar);+ if (mapped !== undefined) {+ return {+ envVar,+ message: `${envVar} maps to config key ${mapped.join('.')}, which is not env-configurable — set it in the config file instead.`,+ };+ }+ for (const known of RECOGNIZED_ENV_VARS.keys()) {+ if (known !== 'PORT' && levenshtein(envVar, known) <= 2) {+ return { envVar, message: `Unknown variable ${envVar} — did you mean ${known}?` };+ }+ }+ return null;+}++/**+ * Overlay a higher-precedence config layer (env values, flag values) onto a+ * base config object. Plain objects merge; scalars and arrays replace (lists+ * replace, never merge). Scope-agnostic by design — precedence between the+ * FILE layers is `mergeLayered`'s job; an env/flag layer sits above all of+ * them and its values are already leaf-validated.+ */+export function applyConfigOverlay(+ base: Record<string, unknown>,+ overlay: Record<string, unknown>,+): Record<string, unknown> {+ const out: Record<string, unknown> = { ...base };+ for (const [key, value] of Object.entries(overlay)) {+ if (value === undefined) continue;+ const existing = out[key];+ out[key] =+ isPlainRecord(value) && isPlainRecord(existing) ? applyConfigOverlay(existing, value) : value;+ }+ return out;+}++function isPlainRecord(value: unknown): value is Record<string, unknown> {+ return typeof value === 'object' && value !== null && !Array.isArray(value);+}++/**+ * Parse the recognized env surface out of `env`. Throws {@link EnvVarError}+ * on a malformed value (boot error); returns did-you-mean diagnostics for+ * suspicious unknown `OK_*` vars. Pure — pass `process.env` at the call site.+ */+export function resolveEnvConfigLayer(env: Record<string, string | undefined>): EnvConfigLayer {+ const overrides: EnvOverride[] = [];+ const diagnostics: EnvDiagnostic[] = [];+ const mechanicalTable = mechanicalEnvNameTable();++ for (const [envVar, path] of RECOGNIZED_ENV_VARS) {+ const raw = env[envVar];+ // Empty/whitespace reads as unset — the `PORT=''` platform quirk, and+ // consistent with the pre-engine `process.env.PORT ? … : undefined` read.+ if (raw === undefined || raw.trim() === '') continue;+ const leaf = resolveLeafSchema(ConfigSchema, path);+ if (leaf === undefined) {+ throw new EnvVarError(envVar, `internal: config path ${path.join('.')} does not resolve`);+ }+ const parsed = parseByLeafType(envVar, raw.trim(), leaf);+ const checked = leaf.safeParse(parsed);+ if (!checked.success) {+ // Surface every validation issue, not just the first — a leaf can fail+ // more than one refinement and reporting one at a time is a slow fix loop.+ const detail = checked.error.issues.map((i) => i.message).join('; ') || 'invalid value';+ throw new EnvVarError(envVar, `${detail} (got ${JSON.stringify(raw)})`);+ }+ overrides.push({ path, envVar, value: checked.data });+ }++ for (const envVar of Object.keys(env)) {+ if (!envVar.startsWith('OK_') || RECOGNIZED_ENV_VARS.has(envVar)) continue;+ if (env[envVar] === undefined) continue;+ const diagnostic = diagnoseUnknownOkVar(envVar, mechanicalTable);+ if (diagnostic !== null) diagnostics.push(diagnostic);+ }++ const layer: Record<string, unknown> = {};+ for (const { path, value } of overrides) {+ let cursor = layer;+ for (const segment of path.slice(0, -1)) {+ cursor[segment] ??= {};+ cursor = cursor[segment] as Record<string, unknown>;+ }+ cursor[path[path.length - 1] as string] = value;+ }++ return { overrides, layer, diagnostics };+}diff --git a/packages/core/src/config/merge-layered.test.ts b/packages/core/src/config/merge-layered.test.tsindex e2f8e29bb..7b83ef797 100644--- a/packages/core/src/config/merge-layered.test.ts+++ b/packages/core/src/config/merge-layered.test.ts@@ -163,17 +163,17 @@ describe('mergeLayered — scope-aware leaf short-circuits', () => {expect(merged.autoSync?.enabled).toBe(false);});- test("scope: 'project-local' falls back to project when project-local is null (backward compat)", () => {+ test("scope: 'project-local' with null local no longer inherits the committed project value", () => {+ // POSTURE FLIP (project-local skips the committed layer): a project-local+ // leaf cleared to `null` on this machine falls through to USER, then the+ // schema default (autoSync.enabled → null) — NEVER the committed project+ // value. A per-machine key must not inherit a cloned value, null or absent.const user = makeConfig({});const project = makeConfig({ autoSync: { enabled: true } });const projectLocal = makeConfig({ autoSync: { enabled: null } });- // `??` treats null + undefined alike — null in project-local falls through- // to project, mirroring the existing scope: 'project' (project ?? user)- // contract. This matches the server's readProjectAutoSyncMode which- // checks `!== null && !== undefined` before short-circuiting.const merged = mergeLayered(user, project, projectLocal);- expect(merged.autoSync?.enabled).toBe(true);+ expect(merged.autoSync?.enabled).toBeNull();});test("scope: 'project-local' returns null when every layer is null (no fallback below user)", () => {@@ -185,13 +185,15 @@ describe('mergeLayered — scope-aware leaf short-circuits', () => {expect(merged.autoSync?.enabled).toBeNull();});- test("scope: 'project-local' falls through to project when project-local has no key", () => {+ test("scope: 'project-local' unset locally ignores the committed project value", () => {+ // POSTURE FLIP: an unset project-local leaf skips the committed project+ // layer and resolves to the schema default (null), not the committed value.const user = makeConfig({});const project = makeConfig({ autoSync: { enabled: true } });const projectLocal = makeConfig({ autoSync: {} });const merged = mergeLayered(user, project, projectLocal);- expect(merged.autoSync?.enabled).toBe(true);+ expect(merged.autoSync?.enabled).toBeNull();});test("scope: 'project-local' falls through to user when project + project-local both omit it", () => {@@ -237,10 +239,11 @@ describe('mergeLayered — scope-aware leaf short-circuits', () => {test("scope: 'project-local' (server.allowExternal) ignores a committed project value", () => {// Exposure consent has the terminal.enabled posture: a committed// `allowExternal: true` must never grant consent on a cloner's machine —- // only this machine's gitignored project-local layer can. A fresh clone's- // project-local layer parses to schema defaults, so `allowExternal` is a- // DEFINED false there and the project-local short-circuit never falls- // through to the committed value.+ // only this machine's gitignored project-local layer can. The project-local+ // scope rule skips the committed project layer structurally, so the leaf+ // resolves through user to the schema default `false` (here the parsed+ // layers make user's default a defined `false`; on the loader's raw path an+ // unset leaf reaches the same default at the final parse).const user = makeConfig({});const project = makeConfig({ server: { allowExternal: true } });const projectLocal = makeConfig({});@@ -271,30 +274,52 @@ describe('mergeLayered — backward compat for two-layer call sites', () => {expect(merged.appearance?.theme).toBe('dark');});- test('mergeLayered(user, project) with project-local-scope field falls through to project', () => {+ test('mergeLayered(user, project) ignores a committed project-local-scope value', () => {+ // POSTURE FLIP: the two-layer path also skips the committed project layer+ // for project-local leaves, so a committed value never wins — it falls to+ // user, then the schema default (null).const user = makeConfig({});const project = makeConfig({ autoSync: { enabled: true } });const merged = mergeLayered(user, project);- expect(merged.autoSync?.enabled).toBe(true);+ expect(merged.autoSync?.enabled).toBeNull();});- test('two-layer merge passes a committed allowExternal:true through — Wave 4 enforcement MUST use the three-layer merge', () => {- // Tripwire, not endorsement. With no project-local layer, layers[2] is- // undefined, so the project-local short-circuit falls through to the- // committed project value — the UNSAFE result for exposure consent (a- // committed `true` would arm a cloner's machine). The three-layer path is- // safe because a parsed project-local layer supplies a DEFINED `false`- // default that wins (see the project-local scope test above). The Wave 4- // boot interlock must therefore resolve `allowExternal` over all three- // layers, per the requiresExternalConsent doc comment — this test exists so- // that requirement surfaces mechanically if someone reaches for the- // two-layer path.+ test('a committed allowExternal:true never passes through, even via the two-layer merge', () => {+ // POSTURE FLIP of the former "two-layer is unsafe" tripwire. The+ // project-local scope rule now skips the committed project layer+ // unconditionally, so a committed `server.allowExternal: true` can never+ // arm consent — with or without a project-local layer. The old safety+ // depended on a parsed project-local layer supplying a DEFINED `false`;+ // the structural skip replaces it and also holds on the RAW-layer path the+ // loader uses (an unset local leaf is `undefined` → falls to the user+ // layer's default `false`).const user = makeConfig({});const project = makeConfig({ server: { allowExternal: true } });const merged = mergeLayered(user, project);- expect(merged.server?.allowExternal).toBe(true);+ expect(merged.server?.allowExternal).toBe(false);+ });++ test('RAW-layer path: a committed allowExternal is skipped, an unset local leaf falls to the schema default', () => {+ // The loader's actual inputs are RAW (un-parsed) partials, not+ // ConfigSchema.parse output. Pin that on that path a committed project+ // `allowExternal: true` with an empty project-local layer surfaces no+ // `allowExternal` from the merge (→ the final parse fills the default+ // false), while a user-global value is still honored as a personal default.+ const committedLeak = mergeLayered({}, { server: { allowExternal: true } }, {});+ expect(+ (committedLeak.server as { allowExternal?: boolean } | undefined)?.allowExternal,+ ).toBeUndefined();++ const userGlobalDefault = mergeLayered(+ { server: { allowExternal: true } },+ { server: { allowExternal: false } },+ {},+ );+ expect(+ (userGlobalDefault.server as { allowExternal?: boolean } | undefined)?.allowExternal,+ ).toBe(true);});});diff --git a/packages/core/src/config/merge-layered.ts b/packages/core/src/config/merge-layered.tsindex 5a5ba2199..2823a48a9 100644--- a/packages/core/src/config/merge-layered.ts+++ b/packages/core/src/config/merge-layered.ts@@ -12,13 +12,30 @@* undefined (project-local ignored unless the field* is also a `'project-local'` leaf — which can't* happen, scopes are exclusive)- * - `'project-local'`→ project-local wins, falling back to project then- * user when undefined+ * - `'project-local'`→ project-local wins, falling back DIRECTLY to user+ * (a personal default across projects) — NEVER the+ * committed project layer. A project-local key is+ * per-machine and gitignored; a value for it in the+ * committed `.ok/config.yml` travels via clone/sync/+ * share, so inheriting it would let a repo arm consent+ * (`server.allowExternal`), a terminal grant, etc. on a+ * cloner's machine. Skipping the project layer closes+ * that leak structurally — it no longer depends on the+ * project-local file being schema-parsed so a defined+ * default can win (the loader now merges RAW layers and+ * parses once, so unset project-local leaves are+ * `undefined` here → the leaf's schema default fills at+ * the final parse).* - `'either'` / no → default deep-merge precedence (project-local >* project > user)** Object branches deep-merge. Arrays replace wholesale (matches* `applyPatchToDocument` semantics + RFC 7396 §1).+ *+ * Layers are RAW (un-parsed) partials from the loader — an unset leaf is+ * absent (`undefined`), which is what makes the cross-layer fallback and the+ * project-local skip work. A single `ConfigSchema.parse` on the merged result+ * fills defaults afterward.*/import type { Config } from './schema.ts';@@ -26,13 +43,29 @@ import { ConfigSchema } from './schema.ts';import { getLeafFieldMeta } from './schema-leaf.ts';/**- * Merge user / project / project-local layers into a single Config.+ * A config layer accepted by `mergeLayered`. Callers pass either fully-parsed+ * `Config` objects (the app's Settings/editor merge) or raw un-parsed partials+ * (the CLI loader's raw-merge-then-parse-once path — an unset leaf is absent,+ * so cross-layer fallback and the project-local skip work). `Config` is+ * assignable to this via its `[x: string]: unknown` index signature.+ */+type ConfigLayer = Config | Record<string, unknown>;++/**+ * Merge user / project / project-local layers into a single `Config`-shaped+ * object. The result is typed `Config` for callers that pass parsed layers and+ * use it directly (the app); the CLI loader passes raw partials and runs one+ * `ConfigSchema.parse` on the result to validate + fill defaults.** `projectLocal` is optional so existing call sites that pre-date the* project-local layer continue to compile. When omitted, the merge* behaves like the prior two-layer version.*/-export function mergeLayered(user: Config, project: Config, projectLocal?: Config): Config {+export function mergeLayered(+ user: ConfigLayer,+ project: ConfigLayer,+ projectLocal?: ConfigLayer,+): Config {return mergeDeep([user, project, projectLocal], []) as Config;}@@ -41,7 +74,18 @@ function mergeDeep(layers: readonly unknown[], path: (string | number)[]): unknoconst meta = getLeafFieldMeta(ConfigSchema, path);if (meta?.scope === 'user') return layers[0];if (meta?.scope === 'project') return layers[1] ?? layers[0];- if (meta?.scope === 'project-local') return layers[2] ?? layers[1] ?? layers[0];+ // project-local: local, else user — the committed project layer (index 1)+ // is deliberately skipped so a committed value never travels to a cloner.+ // DEPENDENCY: the `?? layers[0]` fallback assumes RAW (un-parsed) layers —+ // an undefined project-local layer falls back to user. A caller that passes+ // fully-PARSED Config (schema defaults already filled, e.g. the app) makes+ // layers[2] always defined, so it always wins and never falls back to user.+ // Safe today only because the sole parsed caller doesn't rely on a+ // project-local leaf resolving to a non-default user value (and the+ // security-critical one, allowExternal, defaults false and is never trusted+ // from config-derived consent). A future project-local leaf with a+ // meaningful user fallback would need raw layers or an explicit guard.+ if (meta?.scope === 'project-local') return layers[2] ?? layers[0];}// Default precedence: highest non-undefined layer wins for non-objects;diff --git a/packages/core/src/config/resolve-server-config.test.ts b/packages/core/src/config/resolve-server-config.test.tsindex ec33d8ce2..1477254c8 100644--- a/packages/core/src/config/resolve-server-config.test.ts+++ b/packages/core/src/config/resolve-server-config.test.ts@@ -134,17 +134,33 @@ describe('requiresExternalConsent', () => {expect(requiresExternalConsent(resolved)).toBe(true);});- test('true for a declared public URL, including one alias-read from remote.url', () => {- expect(- requiresExternalConsent(- resolveServerRuntimeConfig(parse({ server: { publicUrl: 'https://kb.example.com' } })),- ),- ).toBe(true);- expect(- requiresExternalConsent(- resolveServerRuntimeConfig(parse({ remote: { url: 'https://kb.example.com' } })),- ),- ).toBe(true);+ test('a committed publicUrl under a loopback bind is inert — does NOT trip the interlock', () => {+ // publicUrl is project-scoped (committed, shared): a team deploying to a+ // VPS commits it. Under a loopback bind it is inert metadata — nothing+ // external reaches the server directly, and a same-box proxy's forwarded+ // requests are still gated at request time. Tripping the boot interlock on+ // publicUrl alone would lock out every teammate who clones the repo and+ // opens it locally (loopback), especially in desktop where config-derived+ // consent is forced off. Only a non-loopback bind is a boot-time question.+ const explicit = resolveServerRuntimeConfig(+ parse({ server: { publicUrl: 'https://kb.example.com' } }),+ );+ expect(explicit.publicUrlSource).toBe('server');+ expect(explicit.loopbackOnly).toBe(true);+ expect(requiresExternalConsent(explicit)).toBe(false);++ // A non-loopback bind WITH a publicUrl still trips it (the bind exposes).+ const exposedWithUrl = resolveServerRuntimeConfig(+ parse({ server: { bind: ['0.0.0.0'], publicUrl: 'https://kb.example.com' } }),+ );+ expect(requiresExternalConsent(exposedWithUrl)).toBe(true);++ // A remote.url alias-read likewise never trips it (loopback bind).+ const aliased = resolveServerRuntimeConfig(+ parse({ remote: { url: 'https://kb.example.com' } }),+ );+ expect(aliased.publicUrlSource).toBe('remote-alias');+ expect(requiresExternalConsent(aliased)).toBe(false);});test('consent state itself does not change whether consent is required', () => {diff --git a/packages/core/src/config/resolve-server-config.ts b/packages/core/src/config/resolve-server-config.tsindex 965f65fd6..5c755a588 100644--- a/packages/core/src/config/resolve-server-config.ts+++ b/packages/core/src/config/resolve-server-config.ts@@ -40,6 +40,16 @@ export interface ServerRuntimeConfig {* `http://localhost:<port>` for a loopback server.*/publicUrl: string | undefined;+ /**+ * Where `publicUrl` came from: the successor key (`'server'`) or the+ * superseded `remote.url` alias (`'remote-alias'`); `undefined` when unset.+ * Load-bearing distinction: a `remote.url` left in config does NOT arm+ * anything by itself (`ok start --remote` is the explicit opt-in), so+ * consumers that treat a declared public origin as an exposure signal —+ * the consent interlock, issued-URL preference — must key off `'server'`+ * only and leave the alias to the legacy remote flow.+ */+ publicUrlSource: 'server' | 'remote-alias' | undefined;/** Exposure consent interlock (see `requiresExternalConsent`). */allowExternal: boolean;/** Open the UI in a browser at start. Derived when not set explicitly. */@@ -75,23 +85,28 @@ export function isLoopbackOnlyBind(bind: readonly string[]): boolean {/*** The single predicate behind the exposure interlock: consent is required- * when the server is reachable beyond this machine — a non-loopback bind- * address, or a declared external origin (`publicUrl`, including one- * alias-read from `remote.url`).+ * when THE SERVER'S OWN BIND reaches beyond this machine — i.e. a non-loopback+ * `server.bind`. `server.publicUrl` deliberately does NOT trip it on its own:+ * publicUrl is a project-scoped, committed, SHARED key (a team deploying to a+ * VPS legitimately commits `https://notes.example.com`), so refusing to boot+ * whenever it is set would lock out every teammate who clones that repo and+ * opens it locally (loopback bind) — especially in desktop, where+ * config-derived consent is forced off. Under a loopback bind a committed+ * publicUrl is inert metadata: nothing external reaches the server directly,+ * and a same-box reverse proxy's forwarded requests are still gated at request+ * time (the forwarded-header tripwire refuses them without consent). Only the+ * actual bind exposing the port is a boot-time consent question; publicUrl's+ * consent need surfaces at request time where a proxy actually appears.*- * Wave 4 wiring requirement: the boot path that enforces this MUST resolve- * `allowExternal` scope-correctly — through `mergeLayered` over all three- * layers (which fills the project-local default so a committed project-file- * value can't win), or by reading the leaf from the project-local layer- * directly. The CLI's `loader.ts` currently merges only user + project with a- * scope-blind deep merge, so consuming its `Config` here would let a- * hand-edited committed `server.allowExternal: true` arm exposure on a- * cloner's machine — the exact leak the project-local scope exists to prevent.+ * The boot path that enforces this MUST resolve `allowExternal`+ * scope-correctly — through `mergeLayered` over all three layers (which skips+ * the committed project layer for the project-local consent leaf), or by+ * reading the leaf from the project-local layer directly.*/export function requiresExternalConsent(- resolved: Pick<ServerRuntimeConfig, 'loopbackOnly' | 'publicUrl'>,+ resolved: Pick<ServerRuntimeConfig, 'loopbackOnly'>,): boolean {- return !resolved.loopbackOnly || resolved.publicUrl !== undefined;+ return !resolved.loopbackOnly;}/**@@ -132,11 +147,18 @@ export function resolveServerRuntimeConfig(config: Config | undefined): ServerRuconst port = server?.port ?? remote?.port;const legacyUrl = remote?.url === '' ? undefined : remote?.url;const publicUrl = server?.publicUrl ?? legacyUrl;+ const publicUrlSource =+ server?.publicUrl !== undefined+ ? ('server' as const)+ : legacyUrl !== undefined+ ? ('remote-alias' as const)+ : undefined;return {port,bind,publicUrl,+ publicUrlSource,allowExternal: server?.allowExternal ?? false,openBrowser: server?.openBrowser ?? loopbackOnly,idleShutdown: server?.idleShutdown ?? (loopbackOnly ? DEFAULT_LOOPBACK_IDLE_SHUTDOWN : 'off'),diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 8051bff96..d122826c6 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -165,6 +165,17 @@ export {type OkignoreDocProvider,type OkignoreUnsubscribe,} from './config/bind-okignore-doc.ts';+export {+ applyConfigOverlay,+ type EnvConfigLayer,+ type EnvDiagnostic,+ type EnvOverride,+ EnvVarError,+ mechanicalEnvName,+ mechanicalEnvNameTable,+ RECOGNIZED_ENV_VARS,+ resolveEnvConfigLayer,+} from './config/env-layer.ts';export {type ConfigDiagnostic,ConfigDiagnosticSchema,@@ -1836,6 +1847,7 @@ export {resolveAssetProjectPath,} from './utils/link-targets.ts';export { type BasenameIndex, createBasenameIndex } from './utils/path-resolve.ts';+export { randomUUID } from './utils/random-uuid.ts';export { type ResolvedInternalHref, resolveInternalHref } from './utils/resolve-internal-href.ts';export { sanitizeFolderName } from './utils/sanitize-folder-name.ts';export { sleep } from './utils/sleep.ts';diff --git a/packages/core/src/utils/identity.ts b/packages/core/src/utils/identity.tsindex 1ad55420f..90a616564 100644--- a/packages/core/src/utils/identity.ts+++ b/packages/core/src/utils/identity.ts@@ -1,4 +1,5 @@import type { Identity } from '../types/identity';+import { randomUUID } from './random-uuid.ts';// --- Constants ---@@ -312,7 +313,7 @@ function safeLocalStorageSet(key: string, value: string): void {export function getIdentity(): Identity {const params = new URLSearchParams(window.location.search);const coeditor = params.get('coeditor') || 'standalone';- const tabId = crypto.randomUUID();+ const tabId = randomUUID();let name = safeLocalStorageGet(LS_NAME_KEY);let color = safeLocalStorageGet(LS_COLOR_KEY);diff --git a/packages/core/src/utils/random-uuid.test.ts b/packages/core/src/utils/random-uuid.test.tsnew file mode 100644index 000000000..31d13bc42--- /dev/null+++ b/packages/core/src/utils/random-uuid.test.ts@@ -0,0 +1,48 @@+import { afterEach, describe, expect, test, vi } from 'vitest';+import { randomUUID } from './random-uuid.ts';++const V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;++afterEach(() => {+ vi.unstubAllGlobals();+});++describe('randomUUID', () => {+ test('uses native crypto.randomUUID when available (secure context / Node)', () => {+ const native = vi.fn(() => '11111111-1111-4111-8111-111111111111');+ vi.stubGlobal('crypto', { randomUUID: native });+ expect(randomUUID()).toBe('11111111-1111-4111-8111-111111111111');+ expect(native).toHaveBeenCalledOnce();+ });++ test('falls back to getRandomValues when randomUUID is absent (insecure http origin)', () => {+ // Simulate a plain-HTTP non-localhost origin: getRandomValues exists,+ // crypto.randomUUID does not. This is the tab-identity module-load crash.+ const real = globalThis.crypto;+ vi.stubGlobal('crypto', {+ getRandomValues: (a: Uint8Array) => real.getRandomValues(a),+ });+ const id = randomUUID();+ expect(id).toMatch(V4);+ // Distinct across calls (probabilistically certain for 122 random bits).+ expect(randomUUID()).not.toBe(id);+ });++ test('fallback always stamps the version-4 and variant nibbles', () => {+ const real = globalThis.crypto;+ vi.stubGlobal('crypto', {+ getRandomValues: (a: Uint8Array) => real.getRandomValues(a),+ });+ for (let i = 0; i < 500; i++) {+ const id = randomUUID();+ expect(id).toMatch(V4);+ expect(id[14]).toBe('4');+ expect('89ab').toContain(id[19]);+ }+ });++ test('does not throw even with no Web Crypto at all', () => {+ vi.stubGlobal('crypto', undefined);+ expect(randomUUID()).toMatch(V4);+ });+});diff --git a/packages/core/src/utils/random-uuid.ts b/packages/core/src/utils/random-uuid.tsnew file mode 100644index 000000000..35a7d6015--- /dev/null+++ b/packages/core/src/utils/random-uuid.ts@@ -0,0 +1,48 @@+/**+ * Cross-context `crypto.randomUUID()`.+ *+ * `crypto.randomUUID()` is a secure-context-only API in browsers: available on+ * HTTPS and on `localhost` / `127.0.0.1`, but ABSENT (`crypto.randomUUID is not+ * a function`) on a plain-HTTP non-localhost origin — a tailnet IP, a LAN IP, or+ * any direct-IP `http://` access. An exposed Open Knowledge server serves+ * exactly those origins, so a bare `crypto.randomUUID()` at module load throws+ * before React mounts and the page renders blank.+ *+ * `crypto.getRandomValues()` is NOT secure-context-gated, so we synthesize an+ * RFC 4122 version-4 UUID from it whenever `randomUUID` is unavailable. Node and+ * secure browser contexts keep taking the native path.+ */++const BYTE_TO_HEX: readonly string[] = Array.from({ length: 256 }, (_, i) =>+ (i + 0x100).toString(16).slice(1),+);++export function randomUUID(): string {+ const c = globalThis.crypto as Crypto | undefined;+ if (c && typeof c.randomUUID === 'function') {+ return c.randomUUID();+ }++ const bytes = new Uint8Array(16);+ if (c && typeof c.getRandomValues === 'function') {+ c.getRandomValues(bytes);+ } else {+ // Last resort (no Web Crypto at all) — not cryptographically strong, but it+ // keeps identity generation from throwing. Unreachable in the browser + Node+ // targets we ship; present only so this function is total.+ for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);+ }++ // RFC 4122 §4.4: version 4 in the high nibble of byte 6, variant 10xx in byte 8.+ bytes[6] = (bytes[6] & 0x0f) | 0x40;+ bytes[8] = (bytes[8] & 0x3f) | 0x80;++ const h = BYTE_TO_HEX;+ return (+ `${h[bytes[0]]}${h[bytes[1]]}${h[bytes[2]]}${h[bytes[3]]}-` ++ `${h[bytes[4]]}${h[bytes[5]]}-` ++ `${h[bytes[6]]}${h[bytes[7]]}-` ++ `${h[bytes[8]]}${h[bytes[9]]}-` ++ `${h[bytes[10]]}${h[bytes[11]]}${h[bytes[12]]}${h[bytes[13]]}${h[bytes[14]]}${h[bytes[15]]}`+ );+}diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex b2b236b94..c168602c5 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -619,6 +619,12 @@ import {scanInPlaceSkills,standardSkillRoots,} from './in-place-skills.ts';+import {+ buildIngressPolicy,+ type IngressPolicy,+ isHostAdmitted,+ isPeerAdmitted,+} from './ingress-policy.ts';import { initContent } from './init-project.ts';import { guardedFetch } from './link-preview/guarded-fetch.ts';import { buildLinkPreviewMetadata, type GuardedFetch } from './link-preview/metadata.ts';@@ -641,10 +647,6 @@ import {runPatSubprocess,} from './local-ops/index.ts';import { getLogger } from './logger.ts';-import {- isAllowedWorkspaceHostHeader as isAllowedWorkspaceHostHeaderBase,- isLoopbackAddress,-} from './loopback.ts';import {managedArtifactAbsPath,managedArtifactTimelinePaths,@@ -663,7 +665,6 @@ import {} from './metrics.ts';import { precomputeParse } from './parse-pool.ts';import { isWithinDir, toPosix } from './path-utils.ts';-import { hostHeaderMatchesPublicHost } from './remote-access.ts';import {appendRenameLogEntry,createAncestorShaSetCache,@@ -2316,13 +2317,12 @@ async function renameTrackedPathInGit(export interface ApiExtensionOptions {/**- * The tunnel's public host (from `ResolvedRemoteAccess.publicHost`) when the- * server was started with remote access enabled. Widens the browser-Origin- * allowlists (the `/api/*` CORS gate + the local-op checks) to admit the- * remote SPA's origin. Undefined in local mode — allowlists stay- * loopback-only.+ * The boot-built ingress policy. Drives the browser-Origin allowlists (the+ * `/api/*` CORS gate + the local-op checks), the route-level Host gates,+ * and the route-level peer gates through one object — the same one the WS+ * upgrade path consults. Omitted (test rigs) ⇒ loopback-only defaults.*/- remotePublicHost?: string;+ ingressPolicy?: IngressPolicy;hocuspocus: Hocuspocus;durabilityState: DocumentDurabilityState;sessionManager: AgentSessionManager;@@ -2733,20 +2733,25 @@ export interface CommentDocHooks {export function createApiExtension(options: ApiExtensionOptions,): Extension & { nativeApi: NativeApiHandle; localApi: LocalApiDispatch } {- 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.+ const { durabilityState } = options;+ const ingressPolicy = options.ingressPolicy ?? buildIngressPolicy({});+ // Every local-op call site in this factory inherits the policy's admitted+ // set through this shadow — one choke point, zero per-site churn.const checkLocalOpSecurity = (req: IncomingMessage,res: ServerResponse,opts: { handler: string },- ): boolean => checkLocalOpSecurityBase(req, res, { ...opts, remotePublicHost });+ ): boolean => checkLocalOpSecurityBase(req, res, { ...opts, policy: ingressPolicy });// Same shadow for the route-level Host gates (principal, workspace, metrics,- // the write-path gates): in remote mode the tunnel's public Host is as- // legitimate as a loopback name — the mount's admit gate already vetted it.+ // the write-path gates): every admitted public name (bind literals,+ // declared publicUrl, legacy tunnel host) is as legitimate as a loopback+ // name — the mount's admit gate already vetted the surface.const isAllowedWorkspaceHostHeader = (host: string | undefined): boolean =>- isAllowedWorkspaceHostHeaderBase(host) ||- (remotePublicHost !== undefined && hostHeaderMatchesPublicHost(host, remotePublicHost));+ isHostAdmitted(host, ingressPolicy);+ // Route-level peer gates ride the policy too: loopback always passes;+ // `server.allowExternal` is the sanctioned relaxation.+ const isRoutePeerAdmitted = (remoteAddress: string | undefined): boolean =>+ isPeerAdmitted(remoteAddress, ingressPolicy);const {hocuspocus,sessionManager,@@ -8362,7 +8367,7 @@ export function createApiExtension(// `handleMetricsAgentPresence` and `handleWorkspace` apply.// Authorization runs BEFORE method dispatch so a bad Host never leaks// "verb the endpoint expects" via the 405 response (OWASP ASVS V4.1.1).- if (!isLoopbackAddress(req.socket.remoteAddress)) {+ if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {handler: 'principal',});@@ -8398,7 +8403,7 @@ export function createApiExtension(// entry's UA. Loopback + Host-header gated — same pattern as// `handlePrincipal` / `handleMetricsAgentPresence`. Disclosed fields// (full request headers, remote address) are local-editing-only signals.- if (!isLoopbackAddress(req.socket.remoteAddress)) {+ if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {handler: 'embed-detect',});@@ -8452,7 +8457,7 @@ export function createApiExtension(// to us via `localhost` / `127.0.0.1` / `[::1]`, matching the mitigation// in the Ethereum/geth JSON-RPC lineage. Same-origin fetches from the// editor app pass; cross-origin rebinding attempts are refused.- if (!isLoopbackAddress(req.socket.remoteAddress)) {+ if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {handler: 'workspace',});@@ -21727,7 +21732,7 @@ export function createApiExtension(const runApiPipeline = createApiRequestPipeline({log,- remotePublicHost,+ policy: ingressPolicy,ephemeral,table: apiRouteTable,});@@ -21768,7 +21773,7 @@ export function createApiExtension(const groupDispatches = nativeGroups.map((group) =>createApiRequestPipeline({log,- remotePublicHost,+ policy: ingressPolicy,ephemeral,table: group.table,}),diff --git a/packages/server/src/boot.test.ts b/packages/server/src/boot.test.tsindex bd45a5e35..f9ca8426a 100644--- a/packages/server/src/boot.test.ts+++ b/packages/server/src/boot.test.ts@@ -4,13 +4,23 @@ import { describe as _bunDescribe, afterEach, beforeEach, expect, test, vi } fro// Tests run normally locally; follow-up will narrow the leak surface.const describe = process.env.CI ? _bunDescribe.skip : _bunDescribe;+// Runs even on CI. The exposure-consent interlock and multi-address bind are+// 7879's core exposure-safety behavior — shipping them with zero CI regression+// protection is a real gap, and the skip's stale Bun-reaping rationale does not+// apply under Node/vitest (these boot in-process; they only git-init in setup).+// Guardrail: GHA is a different env and these boot tests are load-flaky locally+// — treat the first CI run as the verdict. If they flake on GHA, move them back+// under `describe` and cover them in a focused follow-up rather than let flake+// block the security PR.+const describeEvenOnCI = _bunDescribe;+import { execFile } from 'node:child_process';import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';import { mkdtemp, rm } from 'node:fs/promises';import { hostname, tmpdir } from 'node:os';import { resolve } from 'node:path';import { promisify } from 'node:util';-import { emitToleranceFire, OK_DIR } from '@inkeep/open-knowledge-core';+import { emitToleranceFire, OK_DIR, resolveServerRuntimeConfig } from '@inkeep/open-knowledge-core';import { context, metrics, propagation, trace } from '@opentelemetry/api';import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';import { W3CTraceContextPropagator } from '@opentelemetry/core';@@ -1133,3 +1143,173 @@ describe('parseKeepaliveConnectionId', () => {expect(parseKeepaliveConnectionId('/collab/keepalive')).toBeNull();});});++describeEvenOnCI('bootServer — exposure consent interlock', () => {+ // `passServerRuntime` mirrors the CLI path (an explicit, scope-correctly+ // resolved runtime). When false (the desktop / embedder path), only the+ // committed `config` is passed and bootServer's fallback forces consent off.+ async function tryBoot(+ server: Record<string, unknown>,+ passServerRuntime = false,+ ): Promise<unknown> {+ const contentDir = mkdtempSync(resolve(tmpDir, 'interlock-'));+ await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);+ seedOkScaffold(contentDir);+ const config = ConfigSchema.parse({ server });+ try {+ const booted = await bootServer({+ host: '127.0.0.1',+ config,+ ...(passServerRuntime ? { serverRuntime: resolveServerRuntimeConfig(config) } : {}),+ contentDir,+ port: 0,+ quiet: true,+ gitEnabled: false,+ idleShutdownMs: null,+ attachUiSibling: false,+ });+ await booted.destroy();+ } catch (err) {+ return err;+ }+ return null;+ }++ test('non-loopback bind without consent refuses to boot with the one-line fix', async () => {+ const err = await tryBoot({ bind: ['127.0.0.1', '100.64.0.7'] });+ expect(err).toBeInstanceOf(Error);+ const e = err as Error;+ expect(e.constructor.name).toBe('ExposureConsentError');+ expect(e.message).toContain('would bind a non-loopback address');+ expect(e.message).toContain('OK_ALLOW_EXTERNAL=1');+ expect(e.message).toContain('.ok/local/config.yml');+ });++ test('a committed publicUrl under a loopback bind is inert — boots, no lockout (CLI path)', async () => {+ // publicUrl is project-scoped (committed, shared); a team commits their VPS+ // origin. Under a loopback bind it must NOT trip the interlock, or every+ // teammate cloning that repo and opening it locally would be locked out.+ const err = await tryBoot({ publicUrl: 'https://notes.example.com' }, true);+ expect((err as Error | null)?.constructor.name).not.toBe('ExposureConsentError');+ });++ test('a committed publicUrl under a loopback bind is inert — boots on the desktop / embedder path too', async () => {+ // Same, with NO explicit serverRuntime (the desktop utility path). A repo+ // committing publicUrl for its VPS deploy opens fine in desktop.+ const err = await tryBoot({ publicUrl: 'https://notes.example.com' });+ expect((err as Error | null)?.constructor.name).not.toBe('ExposureConsentError');+ });++ test('a loopback-only server with no publicUrl never trips the interlock', async () => {+ // Reaches past the interlock and boots; success is the absence of an+ // ExposureConsentError (any later failure would be a different class).+ const err = await tryBoot({});+ expect((err as Error | null)?.constructor.name).not.toBe('ExposureConsentError');+ });++ test('an explicit (scope-correct) serverRuntime with consent admits a non-loopback bind', async () => {+ // The CLI path: consent resolved over all three layers and passed as an+ // explicit serverRuntime. Only this path can arm exposure for a+ // non-loopback bind.+ const err = await tryBoot({ bind: ['127.0.0.1', '100.64.0.7'], allowExternal: true }, true);+ expect((err as Error | null)?.constructor.name).not.toBe('ExposureConsentError');+ });++ test('config-derived allowExternal does NOT satisfy the interlock (desktop / embedder path)', async () => {+ // The clone-leak guard at the boot chokepoint: an embedder that passes+ // only a committed `config` (no explicit serverRuntime) — e.g. the desktop+ // utility building Config from the project .ok/config.yml alone — must not+ // arm consent from a committed `allowExternal: true`. bootServer forces+ // config-derived consent off, so a committed non-loopback bind trips the+ // interlock and refuses rather than exposing a cloner's machine.+ const err = await tryBoot({ bind: ['0.0.0.0'], allowExternal: true });+ expect(err).toBeInstanceOf(Error);+ expect((err as Error).constructor.name).toBe('ExposureConsentError');+ });++ test('a non-loopback host with no bind/serverRuntime still trips the interlock (single-file shape)', async () => {+ // `HOST=0.0.0.0 ok note.md` boots ephemeral single-file mode with only+ // `host` set — no bind, no serverRuntime — so serverRuntime.bind resolves to+ // the loopback default. The interlock must validate the EFFECTIVE bind+ // (opts.host, what the listener actually binds), not just serverRuntime.bind,+ // or the server binds every interface with no consent recorded.+ const contentDir = mkdtempSync(resolve(tmpDir, 'interlock-host-'));+ await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);+ seedOkScaffold(contentDir);+ let err: unknown = null;+ try {+ const booted = await bootServer({+ host: '0.0.0.0',+ config: ConfigSchema.parse({}),+ contentDir,+ port: 0,+ quiet: true,+ gitEnabled: false,+ idleShutdownMs: null,+ attachUiSibling: false,+ });+ await booted.destroy();+ } catch (e) {+ err = e;+ }+ expect(err).toBeInstanceOf(Error);+ expect((err as Error).constructor.name).toBe('ExposureConsentError');+ expect((err as Error).message).toContain('0.0.0.0');+ });+});++describeEvenOnCI('bootServer — multi-address bind', () => {+ test('every bind address answers on the same port; teardown closes all listeners', async () => {+ const contentDir = mkdtempSync(resolve(tmpDir, 'multibind-'));+ await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);+ seedOkScaffold(contentDir);+ // IPv4 + IPv6 loopback: both bindable on any CI runner, and loopback-only+ // so the consent interlock stays out of this test's way.+ const booted = await bootServer({+ host: '127.0.0.1',+ bind: ['127.0.0.1', '::1'],+ config: TEST_CONFIG,+ contentDir,+ port: 0,+ quiet: true,+ gitEnabled: false,+ idleShutdownMs: null,+ attachUiSibling: false,+ });+ try {+ expect(booted.port).toBeGreaterThan(0);+ const v4 = await fetch(`http://127.0.0.1:${booted.port}/healthz`);+ expect(v4.status).toBe(200);+ const v6 = await fetch(`http://[::1]:${booted.port}/healthz`);+ expect(v6.status).toBe(200);+ } finally {+ await booted.destroy();+ }+ // Both listeners are gone after destroy.+ await expect(fetch(`http://[::1]:${booted.port}/healthz`)).rejects.toThrow();+ await expect(fetch(`http://127.0.0.1:${booted.port}/healthz`)).rejects.toThrow();+ });++ test('duplicate bind entries collapse instead of failing with EADDRINUSE', async () => {+ const contentDir = mkdtempSync(resolve(tmpDir, 'multibind-dup-'));+ await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);+ seedOkScaffold(contentDir);+ const booted = await bootServer({+ host: '127.0.0.1',+ bind: ['127.0.0.1', '127.0.0.1'],+ config: TEST_CONFIG,+ contentDir,+ port: 0,+ quiet: true,+ gitEnabled: false,+ idleShutdownMs: null,+ attachUiSibling: false,+ });+ try {+ const res = await fetch(`http://127.0.0.1:${booted.port}/healthz`);+ expect(res.status).toBe(200);+ } finally {+ await booted.destroy();+ }+ });+});diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.tsindex 7a8667969..a2f528f8b 100644--- a/packages/server/src/boot.ts+++ b/packages/server/src/boot.ts@@ -26,10 +26,15 @@ import { homedir } from 'node:os';import { join, resolve } from 'node:path';import {ASSET_EXTENSIONS,+ DEFAULT_SERVER_HOST,EXECUTABLE_BLOCKLIST_EXTENSIONS,INLINE_RENDERABLE_EXTENSIONS,+ isLoopbackOnlyBind,LOCAL_DIR,OK_DIR,+ requiresExternalConsent,+ resolveServerRuntimeConfig,+ type ServerRuntimeConfig,} from '@inkeep/open-knowledge-core';import {resolveGitDir,@@ -60,6 +65,7 @@ import {import { emitPreflightFailureSpan } from './git-preflight-telemetry.ts';import { attachIdleShutdown, type IdleShutdownHandle } from './idle-shutdown.ts';import { scanGlobalInPlaceSkills, scanInPlaceSkills } from './in-place-skills.ts';+import { buildIngressPolicy, ExposureConsentError } from './ingress-policy.ts';import { resolveLocalSinkConfig } from './local-sink-resolver.ts';import { getLogger, loggerFactory, type PinoLogger } from './logger.ts';import { createMcpHttpHandler } from './mcp-http.ts';@@ -248,6 +254,23 @@ export interface BootServerOptions* paths never do. Default false.*/enableRemote?: boolean;+ /**+ * The resolved `server.*` runtime (bind list, publicUrl, consent, derived+ * defaults). The CLI passes the fully-layered resolution (flags > env >+ * project-local > project > user); callers that omit it get a files-only+ * resolution from `opts.config`. One resolution feeds every consumer —+ * issued URLs, and the exposure interlock — so the CLI and a direct+ * embedder can never disagree about what the server thinks its shape is.+ */+ serverRuntime?: ServerRuntimeConfig;+ /**+ * Full bind-address LIST. The first entry is the primary listener (it+ * decides the port); every further entry gets its own listener on the same+ * port sharing the primary's handlers. Omitted ⇒ single listener on+ * `host`. The caller passes the already-precedence-resolved list; the+ * exposure interlock has vetted it via `serverRuntime`.+ */+ bind?: readonly string[];/*** Forwarded to the ACP thread manager — see* `AcpThreadManagerOptions.probeHarnessManagedMcpEntry`. `ok start` and the@@ -574,6 +597,105 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {// live remote client. Keep it up in remote mode.const idleMsOption = remoteAccess !== null ? null : opts.idleShutdownMs;+ // The resolved server.* runtime. The CLI passes its fully-layered+ // resolution (flags > env > project-local > project > user). Direct+ // embedders (desktop utility, dev-server plugin, tests) fall back to a+ // files-only resolution — but that Config is NOT scope-resolved: it carries+ // the committed `.ok/config.yml` alone, so a committed `server.allowExternal`+ // would arm consent from a cloned repo (the exact clone-leak the scope-+ // correct load exists to prevent). Config-derived consent is therefore+ // untrusted here: force `allowExternal` off so only a caller that resolved+ // it scope-correctly (the CLI's explicit `serverRuntime`) can consent. A+ // committed non-loopback bind or `publicUrl` then trips the interlock below+ // — the correct refusal, not a silent exposure. Desktop's own consent path+ // (the network pane writes project-local, and this boot reads all three+ // layers) is a follow-up; until then desktop is loopback-only by construction.+ const serverRuntime = opts.serverRuntime ?? {+ ...resolveServerRuntimeConfig(opts.config),+ allowExternal: false,+ };++ // The addresses the listener will ACTUALLY bind — the single source of truth+ // for BOTH the exposure interlock below and the multi-listener bind later, so+ // the check and the bind can never diverge. This mirrors the `listenAddresses`+ // rule exactly: an explicit `bind` list wins, else the single `host`, else the+ // loopback default. Load-bearing: a caller can pass a non-loopback `host` /+ // `bind` that diverges from the resolved `serverRuntime.bind` (ephemeral+ // single-file mode boots with `HOST=0.0.0.0` and NO bind/serverRuntime), which+ // would otherwise bind wide open while the interlock — reading only+ // serverRuntime.bind — saw loopback and let it through.+ const effectiveBindAddresses =+ opts.bind !== undefined && opts.bind.length > 0+ ? opts.bind+ : [opts.host ?? DEFAULT_SERVER_HOST];++ // The exposure consent interlock: a NON-LOOPBACK bind reaches beyond this+ // machine, and the server refuses to boot without recorded consent. Checked+ // against the EFFECTIVE bind (above) AND the resolved serverRuntime — either+ // being non-loopback trips it. A committed server.publicUrl under a loopback+ // bind is inert metadata and does NOT trip this (see requiresExternalConsent)+ // — that would lock out a teammate who clones a VPS-deploy repo and opens it+ // locally. Enforced here — the single boot chokepoint every launcher goes+ // through — BEFORE locks, auto-init, or the listener, so refusal is fast and+ // side-effect-free. Consent is only ever honored from an explicit+ // `serverRuntime` (scope-correctly resolved by the CLI); config-derived+ // consent was forced off above, so a committed project-file `allowExternal`+ // can never arm this.+ const bindExposes =+ requiresExternalConsent(serverRuntime) || !isLoopbackOnlyBind(effectiveBindAddresses);+ if (bindExposes && !serverRuntime.allowExternal) {+ const exposingAddresses = isLoopbackOnlyBind(effectiveBindAddresses)+ ? serverRuntime.bind+ : effectiveBindAddresses;+ throw new ExposureConsentError(+ `refusing to start: the server would bind a non-loopback address (${exposingAddresses.join(', ')}), which exposes this server beyond this machine. Consent with OK_ALLOW_EXTERNAL=1, or server.allowExternal: true in .ok/local/config.yml.`,+ );+ }++ // ONE ingress policy for the whole listener — HTTP gates, WS upgrade+ // admission, config-doc admission, and the local-op checks all consult this+ // object. Built from the resolved server.* runtime (consent, declared bind+ // literals, publicUrl) plus the legacy remote shape.+ //+ // The policy's admitted Host names come from `serverRuntime.bind` — the+ // DECLARED bind (which Host headers to accept) — NOT the physical+ // `effectiveBindAddresses`. These legitimately differ: a tailnet / VPS deploy+ // declares `server.bind: […, 100.64.0.7]` so the tailnet IP is an admitted+ // Host, even when the process physically binds loopback behind the tailnet's+ // NAT (composition-rig Case 2 pins exactly this — declared `100.64.0.7`,+ // physical `127.0.0.1`). The EXPOSURE interlock above asks the opposite+ // question — "what does the process actually bind?" — so it keys off+ // `effectiveBindAddresses`. Different questions, deliberately different+ // sources; do NOT unify them (doing so drops declared-but-not-physically-+ // bound Hosts from the allowlist → spurious 403s).+ const ingressPolicy = buildIngressPolicy({ serverRuntime, remoteAccess });+ if (+ serverRuntime.allowExternal &&+ !serverRuntime.loopbackOnly &&+ serverRuntime.publicUrlSource !== 'server'+ ) {+ if (ingressPolicy.bindLiterals.length === 0) {+ // Wildcard bind (0.0.0.0 / ::) contributes NO admissible Host name, and+ // with no server.publicUrl the Host allowlist is loopback-only — so+ // every external request 403s and the server is externally unusable+ // despite consent. This is a misconfiguration, not a refusal (a+ // container behind a platform edge that rewrites Host is legitimate),+ // so warn loudly and name the fix.+ log.warn(+ { bind: serverRuntime.bind },+ '[ingress] server.allowExternal is set on a wildcard bind (0.0.0.0/::) with no server.publicUrl — external requests will be REFUSED (403 host-not-allowed) because no external Host name is admitted. Set server.publicUrl to the public origin clients dial (e.g. behind a reverse proxy or platform edge), or bind a specific address instead of a wildcard.',+ );+ } else {+ // A specific non-loopback bind (e.g. a tailnet IP) IS admissible as a+ // Host literal, so direct-IP access works; only friendly names need+ // server.publicUrl.+ log.info(+ { bind: serverRuntime.bind },+ '[ingress] server.allowExternal is set with no server.publicUrl — the bind-address literals are admitted as Host names (direct IP access). Set server.publicUrl to admit a hostname.',+ );+ }+ }+// Lock-kind resolution. Explicit option wins over env. `OK_LOCK_KIND` is// the contract used by the MCP detach-spawn path in// `packages/cli/src/mcp/shim.ts` — direct callers (CLI `ok start`,@@ -702,7 +824,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {const serverInstance = createServer({contentDir: opts.contentDir,projectDir: opts.projectDir,- remotePublicHost: remoteAccess?.publicHost,+ ingressPolicy,contentRoot: opts.contentRoot,port: opts.port,host: opts.host,@@ -749,6 +871,17 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;})();let boundPort = opts.port ?? 0;+ // Issued URLs (MCP serverUrl → preview_url, ACP thread bootstrap) name the+ // declared public origin when one is configured via the successor key —+ // that is the name clients actually type, and a loopback URL handed to a+ // remote agent is unreachable. The remote-alias source stays with the+ // legacy --remote flow (which never rewrote issued URLs), and the+ // server.lock URL stays loopback below: the lock is same-machine discovery+ // by contract.+ const issuedBaseUrl = (): string =>+ serverRuntime.publicUrlSource === 'server' && serverRuntime.publicUrl !== undefined+ ? serverRuntime.publicUrl.replace(/\/+$/, '')+ : `http://${mcpHost}:${boundPort}`;// No-project ephemeral single-file mode mounts NO MCP endpoint:// there are no agent capabilities. `mountMcpAndApi` leaves `/mcp`// unmounted when `mcpHttpHandler` is undefined, so an undefined handler is@@ -759,7 +892,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {contentDir: opts.contentDir,projectDir: opts.projectDir ?? opts.contentDir,config: opts.config,- getServerUrl: () => `http://${mcpHost}:${boundPort}`,+ getServerUrl: () => issuedBaseUrl(),localApi: serverInstance.localApi,log,});@@ -912,7 +1045,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {isIgnoredPath: (rel) => serverInstance.contentFilter.isPathIgnored(rel),getLoadedDocText: (docName) =>hocuspocus.documents.get(docName)?.getText('source').toString() ?? null,- getServerUrl: () => `http://${mcpHost}:${boundPort}`,+ getServerUrl: () => issuedBaseUrl(),getMcpStdioCommand: () => buildOkMcpStdioCommand(opts.localOpCliArgs, boundPort),probeHarnessManagedMcpEntry: opts.probeHarnessManagedMcpEntry,log,@@ -943,7 +1076,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {hocuspocus,nativeApi: serverInstance.nativeApi,mcpHttpHandler,- remoteAccess,+ ingressPolicy,health: {readiness: () => readinessState,degraded: () => degraded,@@ -1016,16 +1149,22 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {// Listen — resolves only after the kernel has bound the port so callers// can probe `port` immediately.- try {- await new Promise<void>((resolveListen, reject) => {- const onError = (err: Error) => reject(err);- httpServer.once('error', onError);- httpServer.listen(opts.port, opts.host, () => {- httpServer.removeListener('error', onError);- resolveListen();- });- });- } catch (err) {+ //+ // Multi-address bind: `server.bind` is a real LIST. The first address is+ // the primary listener (it decides the port — explicit, or+ // kernel-allocated); every further address gets its own `http.Server` on+ // the SAME port, sharing the primary's `request` + `upgrade` listeners by+ // reference. The copy happens after `mountMcpAndApi` and+ // `attachIdleShutdown` have both attached, so routing, WS admission, and+ // idle tracking behave identically on every listener — one composition, N+ // sockets. Duplicate addresses collapse so a repeated entry can't+ // EADDRINUSE against ourselves.+ // Same source as the exposure interlock's `effectiveBindAddresses` (they must+ // agree — see there), with duplicate addresses collapsed so a repeated entry+ // can't EADDRINUSE against ourselves.+ const listenAddresses = [...new Set(effectiveBindAddresses)];+ const primaryAddress = listenAddresses[0];+ const cleanupAfterListenFailure = async (): Promise<void> => {// Listen failed after locks were acquired. Release ui.lock only if we// own it (we yielded to a live holder, that holder keeps advertising);// destroyHocuspocus releases server.lock either way.@@ -1036,15 +1175,80 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {log.warn({ err: releaseErr }, 'releaseUiLock failed during listen-error cleanup');}}- await destroyHocuspocus().catch(() => {- /* best-effort — surface the original listen error */+ await destroyHocuspocus().catch((teardownErr) => {+ // Best-effort — the original listen error is what we ultimately throw,+ // but a teardown failure here can strand resources, so record it rather+ // than swallow it silently (mirrors the releaseUiLock warn above).+ log.warn({ err: teardownErr }, 'destroyHocuspocus failed during listen-error cleanup');});- // Same rationale as the ui.lock error path above: the process may keep- // living after a failed boot, so the deferred-to-exit unlink would strand- // a live-pid draining lock. Release immediately on this error path.+ // The process may keep living after a failed boot, so the+ // deferred-to-exit unlink would strand a live-pid draining lock.+ // Release immediately on this error path.releaseServerLock(lockDir);+ };+ const listenOn = (server: HttpServer, port: number, address: string): Promise<void> =>+ new Promise<void>((resolveListen, reject) => {+ const onError = (err: Error) => reject(err);+ server.once('error', onError);+ server.listen(port, address, () => {+ server.removeListener('error', onError);+ resolveListen();+ });+ });+ try {+ await listenOn(httpServer, opts.port ?? 0, primaryAddress ?? DEFAULT_SERVER_HOST);+ } catch (err) {+ await cleanupAfterListenFailure();throw err;}+ const primaryAddr = httpServer.address();+ const primaryPort =+ typeof primaryAddr === 'object' && primaryAddr !== null ? primaryAddr.port : (opts.port ?? 0);+ const secondaryServers: HttpServer[] = [];+ for (const address of listenAddresses.slice(1)) {+ const secondary = createHttpServer();+ secondary.headersTimeout = httpServer.headersTimeout;+ secondary.requestTimeout = httpServer.requestTimeout;+ for (const listener of httpServer.listeners('request')) {+ secondary.on('request', listener as (...args: unknown[]) => void);+ }+ for (const listener of httpServer.listeners('upgrade')) {+ secondary.on('upgrade', listener as (...args: unknown[]) => void);+ }+ try {+ await listenOn(secondary, primaryPort, address);+ } catch (err) {+ // A secondary bind failure fails the whole boot — a server that+ // silently serves a subset of its configured addresses is a+ // misconfiguration trap. Name the address that failed and how many were+ // already bound (incl. the primary) so the raw EADDRINUSE/EACCES is+ // actionable, then unwind everything already bound.+ log.error(+ {+ err,+ failedAddress: address,+ port: primaryPort,+ alreadyBound: secondaryServers.length + 1,+ },+ '[boot] secondary address bind failed — unwinding all listeners',+ );+ for (const bound of [...secondaryServers, httpServer]) {+ bound.closeAllConnections?.();+ await new Promise<void>((resolveClose) => {+ bound.close((closeErr) => {+ // Best-effort teardown — we still throw the original bind error+ // below — but a close failure here can strand a listener, so record+ // it rather than swallow it.+ if (closeErr) log.warn({ err: closeErr }, '[boot] listener close failed during unwind');+ resolveClose();+ });+ });+ }+ await cleanupAfterListenFailure();+ throw err;+ }+ secondaryServers.push(secondary);+ }// Boot is usable for HTTP from here; record the listen latency. The// background `initAsync` (seed walk + indexes) still runs and feeds the@@ -1134,6 +1338,27 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {if (acpThreadManager !== null) {await runStep('acpThreads.destroy', () => acpThreadManager.destroy());}+ // Secondary bind listeners close BEFORE the primary's mount/wss teardown.+ // They share the primary's request + upgrade listeners BY REFERENCE, so if+ // they kept accepting after `mount.shutdown()` / `mount.wss.close()` removed+ // or closed those handlers on the primary, an upgrade arriving on a+ // secondary in that window would run against an already-torn-down+ // composition. Closing them first shuts the window; the primary teardown+ // below then covers the rest. A close() failure is logged, not swallowed,+ // so a stranded listener leaves a trace.+ await runStep('secondaryListeners.close', async () => {+ for (const secondary of secondaryServers) {+ secondary.closeAllConnections?.();+ await new Promise<void>((resolveClose) => {+ secondary.close((closeErr) => {+ if (closeErr) {+ log.warn({ err: closeErr }, '[boot] secondary listener close failed during teardown');+ }+ resolveClose();+ });+ });+ }+ });await runStep('mount.shutdown', () => mount.shutdown());if (mcpHttpHandler !== undefined) {await runStep('mcpHttpHandler.close', () => mcpHttpHandler.close());diff --git a/packages/server/src/collaboration-host.test.ts b/packages/server/src/collaboration-host.test.tsindex f18e0b8f0..934e6183c 100644--- a/packages/server/src/collaboration-host.test.ts+++ b/packages/server/src/collaboration-host.test.ts@@ -3,6 +3,7 @@ import { createServer } from 'node:http';import { afterEach, describe, expect, test, vi } from 'vitest';import { WebSocket } from 'ws';import { createCollaborationHost } from './collaboration-host.ts';+import { buildIngressPolicy } from './ingress-policy.ts';function createLog() {return {@@ -167,9 +168,12 @@ describe('createCollaborationHost', () => {expect(host.handleUpgrade(forwardedRequest as never, raw as never, Buffer.alloc(0))).toBe(true);expect(raw.destroy).toHaveBeenCalledOnce();expect(hocuspocus.handleConnection).not.toHaveBeenCalled();+ // Posture flip: the tripwire hint names the consent surface+ // (OK_ALLOW_EXTERNAL + OK_PUBLIC_URL) now that it exists, with the+ // legacy --remote flow as the alternative.expect(log.warn).toHaveBeenCalledWith({ url: '/collab', host: 'localhost' },- '[remote] refused proxied WS upgrade; start the server with `ok start --remote <url>`',+ '[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_PUBLIC_URL, or start with `ok start --remote <url>`',);});@@ -179,11 +183,13 @@ describe('createCollaborationHost', () => {const host = createCollaborationHost({hocuspocus,log,- remoteAccess: {- url: 'https://myproject.ngrok.app',- publicHost: 'myproject.ngrok.app',- port: 24_550,- },+ ingressPolicy: buildIngressPolicy({+ remoteAccess: {+ url: 'https://myproject.ngrok.app',+ publicHost: 'myproject.ngrok.app',+ port: 24_550,+ },+ }),});const admittedWs = new EventEmitter();callbackUpgrade(host, admittedWs);@@ -205,6 +211,275 @@ describe('createCollaborationHost', () => {expect(refused.destroy).toHaveBeenCalledOnce();});+ test('under allowExternal consent, plain /collab validates Host (foreign refused, admitted names pass)', () => {+ // The #5 gap: before, plain /collab was gated only under legacy --remote,+ // so consented exposure (allowExternal, no --remote) left it ungated and+ // any Host reached full CRDT read/write. It now runs the consolidated+ // admit gate — loopback + bind literals + publicUrl — under consent too.+ const log = createLog();+ const hocuspocus = createHocuspocus();+ const host = createCollaborationHost({+ hocuspocus,+ log,+ ingressPolicy: buildIngressPolicy({+ serverRuntime: {+ port: undefined,+ bind: ['127.0.0.1', '100.64.0.7'],+ publicUrl: undefined,+ publicUrlSource: undefined,+ allowExternal: true,+ openBrowser: false,+ idleShutdown: 'off',+ loopbackOnly: false,+ },+ }),+ });++ // Foreign Host (DNS-rebinding shape) is refused even under consent.+ const foreign = createSocket();+ expect(+ host.handleUpgrade(request('/collab', 'evil.example'), foreign as never, Buffer.alloc(0)),+ ).toBe(true);+ expect(foreign.destroy).toHaveBeenCalledOnce();+ expect(hocuspocus.handleConnection).not.toHaveBeenCalled();++ // The bind-address literal is an admitted Host (direct-IP access).+ const bindLiteralWs = new EventEmitter();+ callbackUpgrade(host, bindLiteralWs);+ const bindLiteral = createSocket();+ expect(+ host.handleUpgrade(+ request('/collab', '100.64.0.7:55222'),+ bindLiteral as never,+ Buffer.alloc(0),+ ),+ ).toBe(true);+ expect(bindLiteral.destroy).not.toHaveBeenCalled();++ // Loopback still works alongside the exposure.+ const loopbackWs = new EventEmitter();+ callbackUpgrade(host, loopbackWs);+ const loopback = createSocket();+ expect(+ host.handleUpgrade(request('/collab', 'localhost'), loopback as never, Buffer.alloc(0)),+ ).toBe(true);+ expect(loopback.destroy).not.toHaveBeenCalled();+ expect(hocuspocus.handleConnection).toHaveBeenCalledTimes(2);+ });++ test('under allowExternal consent, plain /collab refuses a foreign Origin (CSWSH defense)', () => {+ // CWE-1275: WS upgrades bypass CORS, so a page on a foreign origin can open+ // wss://<publicUrl>/collab — the Host passes (publicUrl) and, under consent,+ // so does the relaxed peer gate. A present-but-foreign Origin is the only+ // signal separating that cross-site hijack from a first-party client, so it+ // MUST be refused here exactly as /collab/thread refuses it. A missing+ // Origin (native / server-to-server client) is admitted.+ const log = createLog();+ const hocuspocus = createHocuspocus();+ const host = createCollaborationHost({+ hocuspocus,+ log,+ ingressPolicy: buildIngressPolicy({+ serverRuntime: {+ port: undefined,+ bind: ['127.0.0.1', '100.64.0.7'],+ publicUrl: 'https://kb.example.com',+ publicUrlSource: 'server',+ allowExternal: true,+ openBrowser: false,+ idleShutdown: 'off',+ loopbackOnly: false,+ },+ }),+ });++ // Attack: the publicUrl Host is admitted, but the foreign Origin is not.+ const attacker = createSocket();+ expect(+ host.handleUpgrade(+ request('/collab', 'kb.example.com', 'https://evil.example'),+ attacker as never,+ Buffer.alloc(0),+ ),+ ).toBe(true);+ expect(attacker.destroy).toHaveBeenCalledOnce();+ expect(hocuspocus.handleConnection).not.toHaveBeenCalled();++ // A first-party page on the publicUrl origin is admitted.+ const firstPartyWs = new EventEmitter();+ callbackUpgrade(host, firstPartyWs);+ const sameOrigin = createSocket();+ expect(+ host.handleUpgrade(+ request('/collab', 'kb.example.com', 'https://kb.example.com'),+ sameOrigin as never,+ Buffer.alloc(0),+ ),+ ).toBe(true);+ expect(sameOrigin.destroy).not.toHaveBeenCalled();++ // A native / server-to-server client carrying no Origin is admitted.+ const nativeWs = new EventEmitter();+ callbackUpgrade(host, nativeWs);+ const noOrigin = createSocket();+ expect(+ host.handleUpgrade(request('/collab', 'kb.example.com'), noOrigin as never, Buffer.alloc(0)),+ ).toBe(true);+ expect(noOrigin.destroy).not.toHaveBeenCalled();+ expect(hocuspocus.handleConnection).toHaveBeenCalledTimes(2);+ });++ test('a PURE-LOCAL /collab (no consent) still refuses a foreign Origin (localhost CSWSH)', () => {+ // Localhost is reachable from any origin and WS bypasses CORS, so a foreign+ // page can open ws://127.0.0.1:<port>/collab against a loopback-only server+ // (peer + Host both loopback). The Origin check is UNCONDITIONAL — it fires+ // even with no consent — so this cross-site hijack is refused. The peer+Host+ // admit gate stays exposure-only (pure-local keeps its historical posture on+ // that axis); only the Origin/CSWSH axis is always on.+ const log = createLog();+ const hocuspocus = createHocuspocus();+ const host = createCollaborationHost({+ hocuspocus,+ log,+ ingressPolicy: buildIngressPolicy({}),+ });++ const attacker = createSocket();+ expect(+ host.handleUpgrade(+ request('/collab', 'localhost', 'https://evil.example'),+ attacker as never,+ Buffer.alloc(0),+ ),+ ).toBe(true);+ expect(attacker.destroy).toHaveBeenCalledOnce();+ expect(hocuspocus.handleConnection).not.toHaveBeenCalled();++ // The first-party app (a loopback Origin) is admitted.+ const appWs = new EventEmitter();+ callbackUpgrade(host, appWs);+ const app = createSocket();+ expect(+ host.handleUpgrade(+ request('/collab', 'localhost', 'http://localhost:5173'),+ app as never,+ Buffer.alloc(0),+ ),+ ).toBe(true);+ expect(app.destroy).not.toHaveBeenCalled();++ // A no-Origin client stays admitted on a pure-local server.+ const nativeWs = new EventEmitter();+ callbackUpgrade(host, nativeWs);+ const native = createSocket();+ expect(+ host.handleUpgrade(request('/collab', 'localhost'), native as never, Buffer.alloc(0)),+ ).toBe(true);+ expect(native.destroy).not.toHaveBeenCalled();+ expect(hocuspocus.handleConnection).toHaveBeenCalledTimes(2);+ });++ test('under allowExternal consent, /collab/keepalive refuses a foreign Origin (CSWSH)', () => {+ // The keepalive channel gates on admitted() in every mode but historically+ // skipped Origin — the same hole as plain /collab, lower value (agent+ // presence + keepalive sockets, no CRDT). Under consent a foreign-origin+ // page passes peer + Host, so the Origin check is the CSWSH defense here too.+ const log = createLog();+ const hocuspocus = createHocuspocus();+ const host = createCollaborationHost({+ hocuspocus,+ log,+ agentPresenceBroadcaster: { setPresence: vi.fn() } as never,+ ingressPolicy: buildIngressPolicy({+ serverRuntime: {+ port: undefined,+ bind: ['127.0.0.1', '100.64.0.7'],+ publicUrl: 'https://kb.example.com',+ publicUrlSource: 'server',+ allowExternal: true,+ openBrowser: false,+ idleShutdown: 'off',+ loopbackOnly: false,+ },+ }),+ });++ // Attack: publicUrl Host is admitted, but the foreign Origin is refused.+ const attacker = createSocket();+ host.handleUpgrade(+ request(+ '/collab/keepalive?connectionId=agent_1&displayName=A&clientName=Claude&colorSeed=s',+ 'kb.example.com',+ 'https://evil.example',+ ),+ attacker as never,+ Buffer.alloc(0),+ );+ expect(attacker.destroy).toHaveBeenCalledOnce();++ // A native MCP client carrying no Origin is admitted.+ const nativeWs = new EventEmitter();+ callbackUpgrade(host, nativeWs);+ const native = createSocket();+ host.handleUpgrade(+ request(+ '/collab/keepalive?connectionId=agent_2&displayName=A&clientName=Claude&colorSeed=s',+ 'kb.example.com',+ ),+ native as never,+ Buffer.alloc(0),+ );+ expect(native.destroy).not.toHaveBeenCalled();+ });++ test('under allowExternal consent, /collab/thread refuses a foreign Origin (CSWSH)', () => {+ // Completes the CSWSH matrix: /collab and /collab/keepalive have consent-mode+ // foreign-Origin tests; thread management is lower value but the same class.+ const log = createLog();+ const hocuspocus = createHocuspocus();+ const host = createCollaborationHost({+ hocuspocus,+ log,+ acpThreadManager: {} as never,+ ingressPolicy: buildIngressPolicy({+ serverRuntime: {+ port: undefined,+ bind: ['127.0.0.1', '100.64.0.7'],+ publicUrl: 'https://kb.example.com',+ publicUrlSource: 'server',+ allowExternal: true,+ openBrowser: false,+ idleShutdown: 'off',+ loopbackOnly: false,+ },+ }),+ });++ // Attack: the publicUrl Host is admitted, but the foreign Origin is refused.+ const attacker = createSocket();+ host.handleUpgrade(+ request('/collab/thread', 'kb.example.com', 'https://evil.example'),+ attacker as never,+ Buffer.alloc(0),+ );+ expect(attacker.destroy).toHaveBeenCalledOnce();+ expect(hocuspocus.handleConnection).not.toHaveBeenCalled();++ // A first-party thread on the publicUrl origin is admitted (message wired).+ const threadWs = new EventEmitter() as EventEmitter & { close: () => void; send: () => void };+ threadWs.close = () => {};+ threadWs.send = () => {};+ callbackUpgrade(host, threadWs);+ const firstParty = createSocket();+ host.handleUpgrade(+ request('/collab/thread', 'kb.example.com', 'https://kb.example.com'),+ firstParty as never,+ Buffer.alloc(0),+ );+ expect(firstParty.destroy).not.toHaveBeenCalled();+ expect(threadWs.listenerCount('message')).toBe(1);+ });+test('bootstraps presence only for a complete valid keepalive identity', () => {const log = createLog();const setPresence = vi.fn();diff --git a/packages/server/src/collaboration-host.ts b/packages/server/src/collaboration-host.tsindex 5e36984b4..92a0e39c8 100644--- a/packages/server/src/collaboration-host.ts+++ b/packages/server/src/collaboration-host.ts@@ -9,16 +9,18 @@ import type { AgentFocusBroadcaster } from './agent-focus.ts';import { toBroadcasterKey, validateAgentId } from './agent-id.ts';import type { AgentPresenceBroadcaster } from './agent-presence.ts';import type { AgentSessionManager } from './agent-sessions.ts';-import { isAllowedApiOrigin } from './api-origin.ts';+import {+ buildIngressPolicy,+ type IngressPolicy,+ isHostAdmitted,+ isOriginAdmitted,+ isPeerAdmitted,+ stampIngressContext,+ tripsForwardedHeaderTripwire,+} from './ingress-policy.ts';import type { PinoLogger } from './logger.ts';-import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';import type { MaintenanceCoordinator } from './maintenance-coordinator.ts';import { handleCollabSocketError, incrementCollabMessageTooLarge } from './metrics.ts';-import {- hasForwardingHeaders,- isRemoteAdmitted,- type ResolvedRemoteAccess,-} from './remote-access.ts';const DEFAULT_KEEPALIVE_GRACE_MS = 10_000;const MAX_COLLAB_MESSAGE_BYTES = 1024 * 1024;@@ -33,7 +35,12 @@ export interface CollaborationHostOptions {maintenanceCoordinator?: MaintenanceCoordinator;keepaliveGraceMs?: number;acpThreadManager?: AcpThreadManager | null;- remoteAccess?: ResolvedRemoteAccess | null;+ /**+ * The boot-built ingress policy — the same object gating the HTTP surface,+ * so upgrades and requests can never disagree. Omitted (test rigs) ⇒ the+ * loopback-only default policy.+ */+ ingressPolicy?: IngressPolicy;}export interface CollaborationHost {@@ -88,7 +95,7 @@ export function createCollaborationHost(options: CollaborationHostOptions): CollmaintenanceCoordinator,acpThreadManager,} = options;- const remoteAccess = options.remoteAccess ?? undefined;+ const ingressPolicy = options.ingressPolicy ?? buildIngressPolicy({});const keepaliveGraceMs = options.keepaliveGraceMs ?? DEFAULT_KEEPALIVE_GRACE_MS;const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_COLLAB_MESSAGE_BYTES });const keepaliveGraceTimers = new Map<string, ReturnType<typeof setTimeout>>();@@ -99,11 +106,16 @@ export function createCollaborationHost(options: CollaborationHostOptions): Collwss.on('error', (err) => log.error({ err }, 'WebSocketServer error'));+ // One admit shape for HTTP and WS: policy peer gate (loopback, or consent)+ // AND policy Host gate (loopback names + admitted public names). Covers the+ // legacy remote flow too — its tunnel host is in the policy's Host set and+ // its peers are loopback (the tunnel connects from loopback).const admitted = (req: IncomingMessage): boolean =>- remoteAccess !== undefined- ? isRemoteAdmitted(req, remoteAccess)- : isLoopbackAddress(req.socket.remoteAddress) &&- isAllowedWorkspaceHostHeader(req.headers.host);+ isPeerAdmitted(req.socket.remoteAddress, ingressPolicy) &&+ isHostAdmitted(+ Array.isArray(req.headers.host) ? req.headers.host[0] : req.headers.host,+ ingressPolicy,+ );const trackSocket = (socket: Duplex, label: string): void => {socket.on('error', (err: NodeJS.ErrnoException) => {@@ -133,9 +145,20 @@ export function createCollaborationHost(options: CollaborationHostOptions): Coll};const handleKeepalive = (req: IncomingMessage, socket: Duplex, head: Buffer): void => {- if (!admitted(req)) {+ // Same CSWSH defense as `/collab/thread` and plain `/collab` (CWE-1275):+ // a present-but-foreign Origin is refused. Lower-value channel (agent+ // presence + session keepalive, no CRDT read/write), but the same class —+ // under consent a foreign-origin page passes peer + Host, so Origin is the+ // only signal that separates it from a first-party client. Unlike plain+ // `/collab`, keepalive runs `admitted()` in every mode, so the Origin check+ // rides along in every mode too; a missing Origin (native MCP clients)+ // stays admitted.+ if (+ !admitted(req) ||+ (req.headers.origin !== undefined && !isOriginAdmitted(req.headers.origin, ingressPolicy))+ ) {log.debug(- { url: req.url, host: req.headers.host },+ { url: req.url, host: req.headers.host, origin: req.headers.origin },'[collab] /collab/keepalive upgrade refused',);socket.destroy();@@ -258,10 +281,13 @@ export function createCollaborationHost(options: CollaborationHostOptions): Coll},'[collab] upgrade received',);- if (remoteAccess === undefined && hasForwardingHeaders(req)) {+ // WS upgrades join the same ingress path as HTTP: stamp the shared+ // actor-carrying context, then run the same policy tripwire + predicates.+ stampIngressContext(req, {});+ if (tripsForwardedHeaderTripwire(req, ingressPolicy)) {log.warn({ url: req.url, host: req.headers.host },- '[remote] refused proxied WS upgrade; start the server with `ok start --remote <url>`',+ '[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_PUBLIC_URL, or start with `ok start --remote <url>`',);socket.destroy();return true;@@ -271,8 +297,7 @@ export function createCollaborationHost(options: CollaborationHostOptions): CollacpThreadManager === undefined ||acpThreadManager === null ||!admitted(req) ||- (req.headers.origin !== undefined &&- !isAllowedApiOrigin(req.headers.origin, remoteAccess?.publicHost))+ (req.headers.origin !== undefined && !isOriginAdmitted(req.headers.origin, ingressPolicy))) {log.debug({ url: req.url, host: req.headers.host, origin: req.headers.origin },@@ -291,8 +316,34 @@ export function createCollaborationHost(options: CollaborationHostOptions): CollhandleKeepalive(req, socket, head);return true;}- if (remoteAccess !== undefined && !isRemoteAdmitted(req, remoteAccess)) {- log.debug({ url: req.url, host: req.headers.host }, '[collab] /collab upgrade refused');+ // Two independent axes gate plain `/collab`:+ //+ // (1) CSWSH defense (CWE-1275) — UNCONDITIONAL, in every mode, exactly as+ // `/collab/thread` and `/collab/keepalive` do it. WebSocket upgrades+ // bypass CORS, and localhost is reachable from any origin, so even a+ // pure-local server is exposed: a page on a foreign origin can open+ // `ws://127.0.0.1:<port>/collab` (loopback peer + loopback Host both+ // pass) and, without an Origin check, gain full CRDT read/write. A+ // present-but-foreign Origin is the only browser-side signal that+ // separates that attack from a first-party client, so refuse it in ALL+ // modes. A missing Origin (native / server-to-server clients) is+ // admitted — those are not CSWSH vectors and legitimately carry none.+ //+ // (2) Peer + Host admission (`admitted()`) — only when EXPOSED (legacy+ // `--remote` OR `allowExternal`). Pure-local keeps its historical+ // ungated posture on this axis; the general loopback+Host-on-everything+ // read-posture flip is a separate PR. Under consent the loopback bind no+ // longer implies a loopback peer, so `admitted()` (loopback + bind+ // literals + publicUrl, identical to the HTTP API gate) keeps direct-IP+ // access matching what `/api` accepts.+ const foreignOrigin =+ req.headers.origin !== undefined && !isOriginAdmitted(req.headers.origin, ingressPolicy);+ const exposed = ingressPolicy.legacyRemote !== undefined || ingressPolicy.allowExternal;+ if (foreignOrigin || (exposed && !admitted(req))) {+ log.debug(+ { url: req.url, host: req.headers.host, origin: req.headers.origin },+ '[collab] /collab upgrade refused',+ );socket.destroy();return true;}diff --git a/packages/server/src/deployment-cases-composition.test.ts b/packages/server/src/deployment-cases-composition.test.tsnew file mode 100644index 000000000..c6c22fea9--- /dev/null+++ b/packages/server/src/deployment-cases-composition.test.ts@@ -0,0 +1,226 @@+/**+ * Acceptance suite for the deployment deck's Case 2 (laptop + tailnet bind)+ * and Case 3 (managed server behind a reverse proxy): every NAME=value drawn+ * on those diagrams does what the slide says, through the REAL composed+ * `bootServer` stack over real sockets, with zero proxy header surgery.+ *+ * What real loopback sockets cannot fake is a non-loopback TCP peer, so the+ * consent-relaxes-the-peer-gate behavior itself is pinned by the+ * `ingress-policy` unit matrix; here every request arrives via loopback+ * (exactly what Case 3's same-box proxy delivers) and the suite exercises+ * the Host/Origin admission, the forwarded-header posture, and the env+ * spellings end to end.+ */++import { mkdtempSync } from 'node:fs';+import { mkdtemp, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolve } from 'node:path';+import { resolveEnvConfigLayer, resolveServerRuntimeConfig } from '@inkeep/open-knowledge-core';+import { afterAll, beforeAll, describe, expect, test } from 'vitest';+import type { BootedServer } from './boot.ts';+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';+import { ConfigSchema } from './config/schema.ts';++let tmpRoot: string;+let case2: BootedServer;+let case3: BootedServer;++/** Case 2 env, exactly as the deck draws it (publicUrl per the corrected slide). */+const CASE2_ENV = {+ OK_BIND: '127.0.0.1 100.64.0.7',+ OK_ALLOW_EXTERNAL: '1',+ OK_PUBLIC_URL: 'http://laptop.tail:55222',+};++/** Case 3 env, exactly as the deck draws it. */+const CASE3_ENV = {+ PORT: '8080',+ OK_PUBLIC_URL: 'https://notes.example.com',+ OK_ALLOW_EXTERNAL: '1',+};++beforeAll(async () => {+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-deploy-cases-'));++ // The rigs boot from the CONFIG the env layer produces, listening on+ // loopback only (CI cannot bind a tailnet address) while the policy sees+ // the full declared bind list. Consent is honored only from an explicit,+ // scope-correctly resolved `serverRuntime` (the CLI path), so each rig+ // passes `resolveServerRuntimeConfig(config)` — config-derived consent+ // alone is forced off at boot (the desktop/embedder clone-leak guard).+ const case2Config = ConfigSchema.parse({ server: resolveEnvConfigLayer(CASE2_ENV).layer.server });+ case2 = await bootCompositionRig(mkdtempSync(resolve(tmpRoot, 'case2-')), {+ config: case2Config,+ serverRuntime: resolveServerRuntimeConfig(case2Config),+ bind: ['127.0.0.1'],+ });+ await case2.ready;++ // Deck pins PORT=8080; the rig keeps the kernel-allocated port so parallel+ // suites can't collide — the PORT=8080 mapping itself is asserted in the+ // env-spelling block below.+ const case3Config = ConfigSchema.parse({+ server: {+ ...(resolveEnvConfigLayer(CASE3_ENV).layer.server as Record<string, unknown>),+ port: undefined,+ },+ });+ case3 = await bootCompositionRig(mkdtempSync(resolve(tmpRoot, 'case3-')), {+ config: case3Config,+ serverRuntime: resolveServerRuntimeConfig(case3Config),+ });+ await case3.ready;+}, 60_000);++afterAll(async () => {+ await Promise.allSettled([case2?.destroy(), case3?.destroy()]);+ await rm(tmpRoot, { recursive: true, force: true });+});++describe('deck env spellings resolve to the booted config', () => {+ test('Case 2: OK_BIND (space-separated) + OK_ALLOW_EXTERNAL=1 + OK_PUBLIC_URL', () => {+ expect(resolveEnvConfigLayer(CASE2_ENV).layer).toEqual({+ server: {+ bind: ['127.0.0.1', '100.64.0.7'],+ allowExternal: true,+ publicUrl: 'http://laptop.tail:55222',+ },+ });+ });++ test('Case 3: platform PORT + OK_PUBLIC_URL + OK_ALLOW_EXTERNAL=1', () => {+ expect(resolveEnvConfigLayer(CASE3_ENV).layer).toEqual({+ server: {+ port: 8080,+ publicUrl: 'https://notes.example.com',+ allowExternal: true,+ },+ });+ });+});++describe('Case 2 — tailnet bind + consent + publicUrl', () => {+ test("a teammate's browser read under the publicUrl Host answers", async () => {+ const res = await rawRequest(case2.port, '/api/server-info', {+ headers: { Host: 'laptop.tail:55222' },+ });+ expect(res.status).toBe(200);+ });++ test("a teammate's mutating write is admitted (Host + Origin from publicUrl)", async () => {+ const res = await rawRequest(case2.port, '/api/create-page', {+ method: 'POST',+ headers: {+ Host: 'laptop.tail:55222',+ Origin: 'http://laptop.tail:55222',+ 'Content-Type': 'application/json',+ },+ body: JSON.stringify({ path: 'case2-teammate.md' }),+ });+ expect(res.status).toBe(200);+ });++ test('the bind-address literal works as a Host with zero extra config', async () => {+ const read = await rawRequest(case2.port, '/api/server-info', {+ headers: { Host: `100.64.0.7:${case2.port}` },+ });+ expect(read.status).toBe(200);+ const write = await rawRequest(case2.port, '/api/create-page', {+ method: 'POST',+ headers: {+ Host: `100.64.0.7:${case2.port}`,+ Origin: `http://100.64.0.7:${case2.port}`,+ 'Content-Type': 'application/json',+ },+ body: JSON.stringify({ path: 'case2-bind-literal.md' }),+ });+ expect(write.status).toBe(200);+ });++ test('an MCP client (no Origin header) is admitted under the publicUrl Host', async () => {+ const res = await rawRequest(case2.port, '/api/create-page', {+ method: 'POST',+ headers: { Host: 'laptop.tail:55222', 'Content-Type': 'application/json' },+ body: JSON.stringify({ path: 'case2-mcp.md' }),+ });+ expect(res.status).toBe(200);+ });++ test('unconfigured names stay refused — consent never widens the name gates', async () => {+ const write = await rawRequest(case2.port, '/api/create-page', {+ method: 'POST',+ headers: { Host: 'evil.example', 'Content-Type': 'application/json' },+ body: JSON.stringify({ path: 'never.md' }),+ });+ expect(write.status).toBe(403);+ expect(parseProblem(write.body).type).toBe('urn:ok:error:host-not-allowed');+ const origin = await rawRequest(case2.port, '/api/server-info', {+ headers: { Host: 'laptop.tail:55222', Origin: 'https://evil.example' },+ });+ expect(origin.status).toBe(403);+ expect(parseProblem(origin.body).type).toBe('urn:ok:error:invalid-origin');+ });++ test('local loopback access keeps working alongside the exposure', async () => {+ const res = await rawRequest(case2.port, '/api/server-info', {+ headers: { Host: `127.0.0.1:${case2.port}` },+ });+ expect(res.status).toBe(200);+ });+});++describe('Case 3 — loopback bind behind a reverse proxy + publicUrl + consent', () => {+ /** What Caddy/nginx deliver: loopback peer, public Host, forwarding headers. */+ const proxied = (extra: Record<string, string> = {}) => ({+ Host: 'notes.example.com',+ 'X-Forwarded-For': '203.0.113.7',+ 'X-Forwarded-Proto': 'https',+ ...extra,+ });++ test('proxied reads answer — forwarded headers are tolerated, not refused', async () => {+ const res = await rawRequest(case3.port, '/api/server-info', { headers: proxied() });+ expect(res.status).toBe(200);+ });++ test('proxied mutating writes are admitted with the public Origin', async () => {+ const res = await rawRequest(case3.port, '/api/create-page', {+ method: 'POST',+ headers: proxied({+ Origin: 'https://notes.example.com',+ 'Content-Type': 'application/json',+ }),+ body: JSON.stringify({ path: 'case3-proxied.md' }),+ });+ expect(res.status).toBe(200);+ });++ test('a wrong Host through the proxy is refused (rebinding shape)', async () => {+ const res = await rawRequest(case3.port, '/api/create-page', {+ method: 'POST',+ headers: {+ Host: 'evil.example',+ 'X-Forwarded-For': '203.0.113.7',+ 'Content-Type': 'application/json',+ },+ body: JSON.stringify({ path: 'never.md' }),+ });+ expect(res.status).toBe(403);+ });++ test('the wrong scheme on the public Origin is refused (scheme-matched)', async () => {+ const res = await rawRequest(case3.port, '/api/server-info', {+ headers: proxied({ Origin: 'http://notes.example.com' }),+ });+ expect(res.status).toBe(403);+ expect(parseProblem(res.body).type).toBe('urn:ok:error:invalid-origin');+ });++ test('same-box loopback consumers keep working (the lock contract)', async () => {+ const res = await rawRequest(case3.port, '/api/server-info', {+ headers: { Host: `127.0.0.1:${case3.port}` },+ });+ expect(res.status).toBe(200);+ });+});diff --git a/packages/server/src/http/admit-request-surface.test.ts b/packages/server/src/http/admit-request-surface.test.tsnew file mode 100644index 000000000..26222bbdc--- /dev/null+++ b/packages/server/src/http/admit-request-surface.test.ts@@ -0,0 +1,112 @@+import type { IncomingMessage, ServerResponse } from 'node:http';+import type { ServerRuntimeConfig } from '@inkeep/open-knowledge-core';+import { describe, expect, test } from 'vitest';+import { buildIngressPolicy } from '../ingress-policy.ts';+import { admitRequestSurface } from './http-app.ts';++// admitRequestSurface is the surface-wide admission prelude the mount runs+// BEFORE dispatch for EVERY request — /mcp, /api, the static SPA shell, and+// project content assets. These pin the #6 fix: under `allowExternal` consent+// (no legacy --remote), it validates Host with the consolidated predicate+// (loopback + bind literals + publicUrl), so a rebound / foreign Host cannot+// read the static shell or content while the peer is admitted.++function req(+ host: string | undefined,+ remoteAddress = '127.0.0.1',+ extraHeaders: Record<string, string> = {},+): IncomingMessage {+ return {+ headers: { ...(host === undefined ? {} : { host }), ...extraHeaders },+ socket: { remoteAddress },+ } as unknown as IncomingMessage;+}++function fakeRes(): { res: ServerResponse; status: () => number | undefined } {+ let status: number | undefined;+ const res = {+ headersSent: false,+ writableEnded: false,+ destroyed: false,+ setHeader() {},+ writeHead(code: number) {+ status = code;+ return this;+ },+ end() {+ return this;+ },+ } as unknown as ServerResponse;+ return { res, status: () => status };+}++const consentPolicy = buildIngressPolicy({+ serverRuntime: {+ port: undefined,+ bind: ['127.0.0.1', '100.64.0.7'],+ publicUrl: 'http://laptop.tail:55222',+ publicUrlSource: 'server',+ allowExternal: true,+ openBrowser: false,+ idleShutdown: 'off',+ loopbackOnly: false,+ } satisfies ServerRuntimeConfig,+});++describe('admitRequestSurface under allowExternal consent', () => {+ test('admits loopback, the bind literal, and the declared publicUrl host', () => {+ for (const host of ['localhost:5173', '100.64.0.7:55222', 'laptop.tail:55222']) {+ const { res, status } = fakeRes();+ expect(admitRequestSurface(req(host), res, consentPolicy, 'test')).toBe(true);+ expect(status()).toBeUndefined();+ }+ });++ test('refuses a foreign Host (rebinding shape) with a 403', () => {+ const { res, status } = fakeRes();+ expect(admitRequestSurface(req('evil.example'), res, consentPolicy, 'test')).toBe(false);+ expect(status()).toBe(403);+ });++ test('Gate 1: refuses forwarding headers the policy does not tolerate, before Gate 2 (403)', () => {+ // The tripwire runs ahead of the Host gate. A pure-local server that never+ // opted into exposure but receives X-Forwarded-* is fronted by an+ // unexpected proxy/tunnel — refuse rather than serve it with full local+ // trust. This pins the composed prelude to the predicate, not just Gate 2.+ const { res, status } = fakeRes();+ expect(+ admitRequestSurface(+ req('localhost', '127.0.0.1', { 'x-forwarded-for': '203.0.113.7' }),+ res,+ buildIngressPolicy({}),+ 'test',+ ),+ ).toBe(false);+ expect(status()).toBe(403);+ });++ test('Gate 1: a consented policy with a publicUrl tolerates forwarding headers', () => {+ // Under consent with a declared publicUrl the server sits behind a reverse+ // proxy / tunnel on purpose, so forwarded headers are expected and+ // tolerated; the Host still gates in Gate 2 (admitted here via publicUrl).+ const { res, status } = fakeRes();+ expect(+ admitRequestSurface(+ req('laptop.tail:55222', '100.64.0.7', { 'x-forwarded-for': '203.0.113.7' }),+ res,+ consentPolicy,+ 'test',+ ),+ ).toBe(true);+ expect(status()).toBeUndefined();+ });++ test('a pure-local policy (no exposure) does NOT Host-gate the surface here', () => {+ // Gate 2 only runs under exposure; pure-local keeps its historical+ // origin-only read posture (the general read-posture flip is a separate PR).+ const local = buildIngressPolicy({});+ const { res, status } = fakeRes();+ expect(admitRequestSurface(req('evil.example'), res, local, 'test')).toBe(true);+ expect(status()).toBeUndefined();+ });+});diff --git a/packages/server/src/http/api-pipeline.ts b/packages/server/src/http/api-pipeline.tsindex efe01b9ac..4940475c2 100644--- a/packages/server/src/http/api-pipeline.ts+++ b/packages/server/src/http/api-pipeline.ts@@ -45,14 +45,16 @@ import {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';+ buildIngressPolicy,+ type IngressPolicy,+ isHostAdmitted,+ isOriginAdmitted,+ isPeerAdmitted,+ stampIngressContext,+} from '../ingress-policy.ts';+import type { PinoLogger } from '../logger.ts';import { getMeter, getTracer, onTelemetryShutdown } from '../telemetry.ts';import { errorResponse } from './error-response.ts';import { REQUEST_ID_HEADER, rememberRequestId, resolveRequestId } from './request-id.ts';@@ -90,11 +92,12 @@ export interface ApiRouteTable {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.+ * The boot-built ingress policy — one object drives the Origin allowlist,+ * the workspace-Host predicate, and the peer gate, exactly as it does for+ * the WS upgrade path and the api-extension's local shadows. Omitted+ * (test rigs) ⇒ the loopback-only default policy.*/- remotePublicHost?: string;+ policy?: IngressPolicy;/** No-project ephemeral single-file mode — gates EVERY `/api/*` request. */ephemeral?: boolean;table: ApiRouteTable;@@ -129,13 +132,13 @@ function httpDurationHist(): ReturnType<ReturnType<typeof getMeter>['createHisto}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 { log, ephemeral, table } = opts;+ const policy = opts.policy ?? buildIngressPolicy({});+ // The policy's Host predicate: loopback names plus every admitted public+ // name (bind literals, declared publicUrl, legacy tunnel host) — the 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));+ isHostAdmitted(host, policy);return async (request, response) => {const url = request.url?.split('?')[0];@@ -184,6 +187,10 @@ export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPi// 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;+ // The actor-carrying request context — one per admitted request, shared+ // shape with the WS upgrade path. The actor slot stays undefined until+ // auth is un-deferred; this is its drop-in point.+ stampIngressContext(request, { requestId });if (requestId !== undefined) {rememberRequestId(request, requestId);if (typeof response.setHeader === 'function') {@@ -238,7 +245,7 @@ export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPi// unit tests that stub only `writeHead` + `end`.if (url.startsWith('/api/')) {const origin = request.headers.origin;- if (origin !== undefined && !isAllowedApiOrigin(origin, remotePublicHost)) {+ if (origin !== undefined && !isOriginAdmitted(origin, policy)) {// 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@@ -296,7 +303,7 @@ export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPi// so the protection remains meaningful for any production path.if (table.isMutating(url)) {const peerAddress = request.socket?.remoteAddress;- if (peerAddress !== undefined && !isLoopbackAddress(peerAddress)) {+ if (peerAddress !== undefined && !isPeerAdmitted(peerAddress, policy)) {errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {handler: 'api-mutating-gate',});@@ -326,7 +333,7 @@ export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPi// non-`/api/` static-serve path.if (ephemeral && url.startsWith('/api/')) {const peerAddress = request.socket?.remoteAddress;- if (peerAddress !== undefined && !isLoopbackAddress(peerAddress)) {+ if (peerAddress !== undefined && !isPeerAdmitted(peerAddress, policy)) {errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {handler: 'api-ephemeral-gate',});diff --git a/packages/server/src/http/http-app.ts b/packages/server/src/http/http-app.tsindex d73b6bba3..b81f504a3 100644--- a/packages/server/src/http/http-app.ts+++ b/packages/server/src/http/http-app.ts@@ -2,12 +2,14 @@ import type { IncomingMessage, ServerResponse } from 'node:http';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';+ buildIngressPolicy,+ type IngressPolicy,+ isHostAdmitted,+ isPeerAdmitted,+ tripsForwardedHeaderTripwire,+} from '../ingress-policy.ts';+import type { PinoLogger } from '../logger.ts';import { errorResponse } from './error-response.ts';/**@@ -55,17 +57,19 @@ export interface NativeApiHandle {* 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.+ * refused. Both gates consult the ONE boot-built `IngressPolicy` — the same+ * object the WS upgrade path and per-route gates consume.*- * 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 1 — tripwire: proxy-forwarding headers the policy does not tolerate+ * mean a tunnel is pointed at a server that never opted into exposure.+ * 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.+ * Gate 2 — with the legacy `--remote` flow armed, ONE admit decision covers+ * every surface (trust-the-tunnel — see remote-access.ts): loopback socket ++ * Host on the allowlist. 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@@ -75,24 +79,35 @@ export interface NativeApiHandle {export function admitRequestSurface(req: IncomingMessage,res: ServerResponse,- remoteAccess: ResolvedRemoteAccess | undefined,+ policy: IngressPolicy,handler: string,): boolean {- if (remoteAccess === undefined && hasForwardingHeaders(req)) {+ if (tripsForwardedHeaderTripwire(req, policy)) {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.',+ 'Proxied request refused: this server has not consented to external exposure. Set OK_PUBLIC_URL to the public origin and OK_ALLOW_EXTERNAL=1 (or server.publicUrl + server.allowExternal in config), or restart with `ok start --remote <url>`.',{ 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;+ // Gate 2 runs whenever the surface is EXPOSED — legacy `--remote` OR+ // `allowExternal` consent. This covers every surface the prelude fronts:+ // `/mcp`, `/api/*`, the static shell, and project-mode content assets. The+ // predicate is the consolidated one (loopback + bind literals + publicUrl),+ // identical to the `/api` pipeline gate, so direct-IP access to the shell/+ // content matches what the API admits. Pure-local (no exposure) keeps its+ // historical origin-only read posture here; the general loopback+Host-on-+ // all-reads flip is a separate PR.+ if (policy.legacyRemote !== undefined || policy.allowExternal) {+ const host = Array.isArray(req.headers.host) ? req.headers.host[0] : req.headers.host;+ if (!isPeerAdmitted(req.socket.remoteAddress, policy) || !isHostAdmitted(host, policy)) {+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {+ handler,+ });+ return false;+ }}return true;}@@ -163,11 +178,11 @@ export interface CreateHttpAppOptions {*/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).+ * The boot-built ingress policy for the surface admission gates on native+ * routes (same object the mount applies to the legacy dispatch). Omitted+ * (test rigs) ⇒ the loopback-only default policy.*/- remoteAccess?: ResolvedRemoteAccess | undefined;+ ingressPolicy?: IngressPolicy;/** Structured logger for handler errors the router catches. */log: PinoLogger;}@@ -249,13 +264,14 @@ export function createHttpApp(opts: CreateHttpAppOptions): HttpAppHandle {// 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 ingressPolicy = opts.ingressPolicy ?? buildIngressPolicy({});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')) {+ if (!admitRequestSurface(req, res, ingressPolicy, 'native-api-surface')) {return RESPONSE_ALREADY_SENT;}try {diff --git a/packages/server/src/index.ts b/packages/server/src/index.tsindex 27f2be366..ac6053b03 100644--- a/packages/server/src/index.ts+++ b/packages/server/src/index.ts@@ -235,6 +235,16 @@ export {attachIdleShutdown,type IdleShutdownHandle,} from './idle-shutdown.ts';+export {+ buildIngressPolicy,+ ExposureConsentError,+ getIngressContext,+ type IngressPolicy,+ type IngressRequestContext,+ isHostAdmitted,+ isOriginAdmitted,+ isPeerAdmitted,+} from './ingress-policy.ts';export {type BuildConfigYmlOptions,buildConfigYmlContent,diff --git a/packages/server/src/ingress-policy.test.ts b/packages/server/src/ingress-policy.test.tsnew file mode 100644index 000000000..d55710867--- /dev/null+++ b/packages/server/src/ingress-policy.test.ts@@ -0,0 +1,277 @@+import type { ServerRuntimeConfig } from '@inkeep/open-knowledge-core';+import { describe, expect, test } from 'vitest';+import {+ buildIngressPolicy,+ getIngressContext,+ isHostAdmitted,+ isOriginAdmitted,+ isPeerAdmitted,+ stampIngressContext,+ tripsForwardedHeaderTripwire,+} from './ingress-policy.ts';++function runtime(overrides: Partial<ServerRuntimeConfig> = {}): ServerRuntimeConfig {+ return {+ port: undefined,+ bind: ['127.0.0.1'],+ publicUrl: undefined,+ publicUrlSource: undefined,+ allowExternal: false,+ openBrowser: true,+ idleShutdown: '30m',+ loopbackOnly: true,+ ...overrides,+ };+}++const LEGACY_REMOTE = {+ url: 'https://myproject.ngrok.app',+ publicHost: 'myproject.ngrok.app',+ port: 24_550,+};++describe('buildIngressPolicy', () => {+ test('empty input yields the loopback-only default policy', () => {+ const policy = buildIngressPolicy({});+ expect(policy.allowExternal).toBe(false);+ expect(policy.bindLiterals).toEqual([]);+ expect(policy.publicOrigin).toBeUndefined();+ expect(policy.legacyRemote).toBeUndefined();+ expect(policy.tolerateForwardedHeaders).toBe(false);+ });++ test('non-loopback bind literals are collected; loopback and wildcards are not', () => {+ const policy = buildIngressPolicy({+ serverRuntime: runtime({+ bind: ['127.0.0.1', '100.64.0.7', '0.0.0.0', '::', 'localhost', '[::1]', '2001:DB8::1'],+ loopbackOnly: false,+ }),+ });+ expect(policy.bindLiterals).toEqual(['100.64.0.7', '2001:db8::1']);+ });++ test('publicOrigin comes from the successor key only, never the remote alias', () => {+ const explicit = buildIngressPolicy({+ serverRuntime: runtime({+ publicUrl: 'http://laptop.tail:55222',+ publicUrlSource: 'server',+ }),+ });+ expect(explicit.publicOrigin).toEqual({ host: 'laptop.tail:55222', protocol: 'http:' });+ const aliased = buildIngressPolicy({+ serverRuntime: runtime({+ publicUrl: 'https://kb.example.com',+ publicUrlSource: 'remote-alias',+ }),+ });+ expect(aliased.publicOrigin).toBeUndefined();+ });++ test('forwarded headers are tolerated only under legacy remote, or consent + declared publicUrl', () => {+ expect(buildIngressPolicy({ remoteAccess: LEGACY_REMOTE }).tolerateForwardedHeaders).toBe(true);+ expect(+ buildIngressPolicy({+ serverRuntime: runtime({+ allowExternal: true,+ publicUrl: 'https://kb.example.com',+ publicUrlSource: 'server',+ }),+ }).tolerateForwardedHeaders,+ ).toBe(true);+ // Consent without a declared public origin does NOT relax the tripwire —+ // a proxy in front of a bind-exposed server still needs publicUrl.+ expect(+ buildIngressPolicy({+ serverRuntime: runtime({ allowExternal: true, loopbackOnly: false }),+ }).tolerateForwardedHeaders,+ ).toBe(false);+ // A declared publicUrl without consent never tolerates them either+ // (that combination is a boot refusal once the interlock enforces).+ expect(+ buildIngressPolicy({+ serverRuntime: runtime({+ publicUrl: 'https://kb.example.com',+ publicUrlSource: 'server',+ }),+ }).tolerateForwardedHeaders,+ ).toBe(false);+ });+});++describe('isPeerAdmitted — consent relaxes the peer gate ONLY', () => {+ test('loopback always passes; external requires allowExternal', () => {+ const local = buildIngressPolicy({});+ expect(isPeerAdmitted('127.0.0.1', local)).toBe(true);+ expect(isPeerAdmitted('::1', local)).toBe(true);+ expect(isPeerAdmitted('100.64.0.9', local)).toBe(false);+ const consented = buildIngressPolicy({+ serverRuntime: runtime({ allowExternal: true, loopbackOnly: false }),+ });+ expect(isPeerAdmitted('100.64.0.9', consented)).toBe(true);+ expect(isPeerAdmitted('203.0.113.7', consented)).toBe(true);+ });++ test('a vanished socket stays refused even with consent', () => {+ const consented = buildIngressPolicy({+ serverRuntime: runtime({ allowExternal: true, loopbackOnly: false }),+ });+ expect(isPeerAdmitted(undefined, consented)).toBe(false);+ });+});++describe('isHostAdmitted — names validate in every mode, never widened by consent', () => {+ const case2 = buildIngressPolicy({+ // Deck Case 2: tailnet bind + consent, publicUrl per the corrected deck.+ serverRuntime: runtime({+ bind: ['127.0.0.1', '100.64.0.7'],+ loopbackOnly: false,+ allowExternal: true,+ publicUrl: 'http://laptop.tail:55222',+ publicUrlSource: 'server',+ }),+ });++ test('loopback names and bind literals (any port) are admitted', () => {+ expect(isHostAdmitted('localhost:5173', case2)).toBe(true);+ expect(isHostAdmitted('100.64.0.7:55222', case2)).toBe(true);+ expect(isHostAdmitted('100.64.0.7', case2)).toBe(true);+ });++ test('the declared publicUrl host is admitted exactly (host:port)', () => {+ expect(isHostAdmitted('laptop.tail:55222', case2)).toBe(true);+ // A different port is a different name — refused.+ expect(isHostAdmitted('laptop.tail:9999', case2)).toBe(false);+ });++ test('unconfigured names stay refused even under consent (rebinding defense)', () => {+ expect(isHostAdmitted('evil.example', case2)).toBe(false);+ expect(isHostAdmitted('evil.example:55222', case2)).toBe(false);+ expect(isHostAdmitted(undefined, case2)).toBe(false);+ });++ test('an IPv6 bind literal matches its bracketed Host form', () => {+ const v6 = buildIngressPolicy({+ serverRuntime: runtime({ bind: ['2001:db8::1'], loopbackOnly: false, allowExternal: true }),+ });+ expect(isHostAdmitted('[2001:db8::1]:8080', v6)).toBe(true);+ expect(isHostAdmitted('[2001:db8::2]:8080', v6)).toBe(false);+ });++ test('a malformed bracketed-IPv6 Host is refused (fail-closed parse)', () => {+ // An opening `[` without a closing `]` fails to parse — it must refuse, not+ // fall through to a loose comparison that could admit an attacker-shaped+ // Host under consent.+ const v6 = buildIngressPolicy({+ serverRuntime: runtime({ bind: ['2001:db8::1'], loopbackOnly: false, allowExternal: true }),+ });+ expect(isHostAdmitted('[2001:db8::1', v6)).toBe(false);+ expect(isHostAdmitted('[2001:db8::1:8080', v6)).toBe(false);+ });+});++describe('isOriginAdmitted — if present, must match; scheme-matched for publicUrl', () => {+ const case3 = buildIngressPolicy({+ // Deck Case 3: loopback bind behind a proxy, https publicUrl + consent.+ serverRuntime: runtime({+ allowExternal: true,+ publicUrl: 'https://notes.example.com',+ publicUrlSource: 'server',+ }),+ });++ test('the declared public origin is admitted; wrong scheme refused', () => {+ expect(isOriginAdmitted('https://notes.example.com', case3)).toBe(true);+ expect(isOriginAdmitted('http://notes.example.com', case3)).toBe(false);+ expect(isOriginAdmitted('https://evil.example.com', case3)).toBe(false);+ });++ test('an http publicUrl admits its http origin (tailnet/LAN posture)', () => {+ const httpPublic = buildIngressPolicy({+ serverRuntime: runtime({+ allowExternal: true,+ publicUrl: 'http://laptop.tail:55222',+ publicUrlSource: 'server',+ }),+ });+ expect(isOriginAdmitted('http://laptop.tail:55222', httpPublic)).toBe(true);+ expect(isOriginAdmitted('https://laptop.tail:55222', httpPublic)).toBe(false);+ });++ test('bind-literal origins are admitted over http or https', () => {+ const bound = buildIngressPolicy({+ serverRuntime: runtime({+ bind: ['100.64.0.7'],+ loopbackOnly: false,+ allowExternal: true,+ }),+ });+ expect(isOriginAdmitted('http://100.64.0.7:55222', bound)).toBe(true);+ expect(isOriginAdmitted('https://100.64.0.7', bound)).toBe(true);+ expect(isOriginAdmitted('ftp://100.64.0.7', bound)).toBe(false);+ });++ test('loopback and the Electron null/file shapes always pass', () => {+ const local = buildIngressPolicy({});+ expect(isOriginAdmitted('http://localhost:5173', local)).toBe(true);+ expect(isOriginAdmitted('null', local)).toBe(true);+ expect(isOriginAdmitted('file://', local)).toBe(true);+ expect(isOriginAdmitted('https://evil.example.com', local)).toBe(false);+ });++ test('a malformed / unparseable Origin fails closed under consent', () => {+ // A garbage Origin must not fall through to admission — even under consent+ // with a declared publicUrl, an Origin that `new URL()` cannot parse is+ // refused rather than loosely compared.+ expect(isOriginAdmitted('http://[not-closed', case3)).toBe(false);+ expect(isOriginAdmitted('://missing-scheme', case3)).toBe(false);+ expect(isOriginAdmitted('not a url', case3)).toBe(false);+ expect(isOriginAdmitted('https://', case3)).toBe(false);+ });+});++describe('tripsForwardedHeaderTripwire', () => {+ test('fires on forwarding headers unless the policy tolerates them', () => {+ const local = buildIngressPolicy({});+ const req = { headers: { 'x-forwarded-for': '203.0.113.7' } };+ expect(tripsForwardedHeaderTripwire(req, local)).toBe(true);+ const consented = buildIngressPolicy({+ serverRuntime: runtime({+ allowExternal: true,+ publicUrl: 'https://notes.example.com',+ publicUrlSource: 'server',+ }),+ });+ expect(tripsForwardedHeaderTripwire(req, consented)).toBe(false);+ expect(tripsForwardedHeaderTripwire({ headers: {} }, local)).toBe(false);+ });++ // Pin EVERY vendor header the tripwire watches, so a refactor that drops one+ // (a Cloudflare / Fastly / RFC 7239 proxy) can't silently stop tripping.+ test.each([+ 'x-forwarded-for',+ 'x-forwarded-proto',+ 'x-forwarded-host',+ 'forwarded',+ 'x-real-ip',+ 'x-client-ip',+ 'x-cluster-client-ip',+ 'cf-connecting-ip',+ 'fastly-client-ip',+ 'true-client-ip',+ ])('fires on the %s forwarding header (non-consented)', (header) => {+ const local = buildIngressPolicy({});+ expect(tripsForwardedHeaderTripwire({ headers: { [header]: 'v' } }, local)).toBe(true);+ });+});++describe('ingress request context', () => {+ test('stamps peer class and the empty actor slot, retrievable by request', () => {+ const req = {+ socket: { remoteAddress: '100.64.0.9' },+ headers: {},+ } as unknown as import('node:http').IncomingMessage;+ const context = stampIngressContext(req, { requestId: 'r-1' });+ expect(context).toEqual({ requestId: 'r-1', peerClass: 'external', actor: undefined });+ expect(getIngressContext(req)).toBe(context);+ });+});diff --git a/packages/server/src/ingress-policy.ts b/packages/server/src/ingress-policy.tsnew file mode 100644index 000000000..ad0fc1326--- /dev/null+++ b/packages/server/src/ingress-policy.ts@@ -0,0 +1,253 @@+/**+ * One ingress policy for every admission gate — HTTP requests AND WebSocket+ * upgrades. Built once at boot from the resolved `server.*` runtime plus the+ * legacy `--remote` shape, then threaded to every gate site: the surface+ * admission prelude (`admitRequestSurface`), the `/api/*` pipeline gates, the+ * `/mcp` gates, the collaboration host's upgrade admission, the config-doc+ * admission, and the local-op security checks. One policy, one set of+ * predicates — the HTTP and WS halves of the server can never disagree about+ * who is admitted.+ *+ * The three predicates and what governs each:+ *+ * - PEER (`isPeerAdmitted`) — the TCP peer address, the only unforgeable+ * signal. Loopback always passes. `server.allowExternal` is the sanctioned+ * relaxation: consent means "an authenticating edge fronts this port; OK+ * may trust non-loopback peers". Nothing else relaxes it.+ * - HOST (`isHostAdmitted`) — the name the client dialed (DNS-rebinding+ * defense). Always validates, in every mode, against loopback names + the+ * non-loopback bind-address literals + the declared `server.publicUrl`+ * host + the legacy tunnel host. Consent does NOT widen this set: an+ * unconfigured name stays refused, so a rebound page presenting the+ * attacker's domain is refused no matter what the peer looks like.+ * - ORIGIN (`isOriginAdmitted`) — browser CSRF defense; "if present, must+ * match" (curl and MCP clients send none). Admits the loopback set, the+ * null/file:// Electron shapes, the bind literals, and the declared+ * public origin scheme-matched against `publicUrl`'s own scheme.+ *+ * Wildcard binds (`0.0.0.0`, `::`) contribute no Host names — they are not+ * nameable addresses. A deployment binding wide needs `server.publicUrl` for+ * any non-loopback name to be admitted; the boot hint says so.+ */++import type { IncomingMessage } from 'node:http';+import type { ServerRuntimeConfig } from '@inkeep/open-knowledge-core';+import { isAllowedApiOrigin } from './api-origin.ts';+import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';+import {+ hasForwardingHeaders,+ hostHeaderMatchesPublicHost,+ normalizeHostHeader,+ type ResolvedRemoteAccess,+} from './remote-access.ts';++export interface IngressPolicy {+ /**+ * Exposure consent (`server.allowExternal`, scope-correctly resolved).+ * Relaxes the loopback-PEER gate only — never Host/Origin validation.+ */+ allowExternal: boolean;+ /**+ * Non-loopback, non-wildcard `server.bind` literals, lowercased with any+ * IPv6 brackets stripped. Admitted as Host/Origin hostnames on any port —+ * rebinding-safe (a rebound page presents the attacker's domain, never+ * your bind address), and what makes `http://<tailnet-ip>:<port>` work+ * with zero extra config.+ */+ bindLiterals: readonly string[];+ /**+ * The declared canonical origin — the EXPLICIT `server.publicUrl` only+ * (`publicUrlSource === 'server'`). `host` is `host[:port]` with default+ * ports stripped; `protocol` is `http:`/`https:`, matched exactly for+ * Origin checks since the key admits http for tailnet/LAN deployments.+ */+ publicOrigin: { host: string; protocol: string } | undefined;+ /** The legacy `ok start --remote` shape (tunnel publicHost; https-only). */+ legacyRemote: ResolvedRemoteAccess | undefined;+ /**+ * Proxy-forwarding headers tolerated (never trusted — addressing and+ * identity stay socket/config-derived). True under the legacy remote flow+ * or under consent with a declared public origin; otherwise their presence+ * trips the proxied-request tripwire.+ */+ tolerateForwardedHeaders: boolean;+}++/**+ * Boot refusal from the exposure consent interlock: the resolved runtime+ * declares external exposure (non-loopback bind, or `server.publicUrl`)+ * without `server.allowExternal`. The message IS the one-line fix; the CLI+ * maps it to EX_CONFIG like the other config-shaped boot errors.+ */+export class ExposureConsentError extends Error {}++export interface BuildIngressPolicyInput {+ /**+ * The resolved `server.*` runtime. Omit for a policy equivalent to the+ * loopback-only default (test rigs, legacy construction sites).+ */+ serverRuntime?: ServerRuntimeConfig | undefined;+ /** Legacy `--remote` resolution; undefined when remote is not armed. */+ remoteAccess?: ResolvedRemoteAccess | null | undefined;+}++/** Loopback / wildcard shapes that never contribute an admissible Host name. */+const NON_NAMEABLE_BINDS = new Set(['0.0.0.0', '::', 'localhost', '::1', '[::1]']);++function normalizeBindLiteral(address: string): string {+ const trimmed = address.trim().toLowerCase();+ return trimmed.startsWith('[') && trimmed.endsWith(']') ? trimmed.slice(1, -1) : trimmed;+}++export function buildIngressPolicy(input: BuildIngressPolicyInput): IngressPolicy {+ const runtime = input.serverRuntime;+ const legacyRemote = input.remoteAccess ?? undefined;++ const bindLiterals =+ runtime === undefined+ ? []+ : runtime.bind+ .map(normalizeBindLiteral)+ .filter((addr) => !NON_NAMEABLE_BINDS.has(addr) && !addr.startsWith('127.'));++ let publicOrigin: IngressPolicy['publicOrigin'];+ if (runtime?.publicUrlSource === 'server' && runtime.publicUrl !== undefined) {+ // The schema guarantees a parseable http(s) URL; a throw here would be a+ // schema/resolver drift bug, so let it propagate loudly at boot.+ const parsed = new URL(runtime.publicUrl);+ publicOrigin = { host: normalizeHostHeader(parsed.host), protocol: parsed.protocol };+ }++ const allowExternal = runtime?.allowExternal === true;+ return {+ allowExternal,+ bindLiterals,+ publicOrigin,+ legacyRemote,+ tolerateForwardedHeaders:+ legacyRemote !== undefined || (allowExternal && publicOrigin !== undefined),+ };+}++/**+ * PEER gate: loopback always passes; `allowExternal` admits any connected+ * peer (the deployer's edge owns who can reach the port). `undefined`+ * (socket gone) stays refused — no basis to attest anything.+ */+export function isPeerAdmitted(remoteAddress: string | undefined, policy: IngressPolicy): boolean {+ if (isLoopbackAddress(remoteAddress)) return true;+ return policy.allowExternal && remoteAddress !== undefined;+}++/** Hostname (no port, no IPv6 brackets, lowercased) of a raw Host header. */+function hostnameOfHostHeader(host: string): string | null {+ if (host.startsWith('[')) {+ const close = host.indexOf(']');+ if (close < 0) return null;+ return host.slice(1, close).toLowerCase();+ }+ const colon = host.lastIndexOf(':');+ return (colon >= 0 ? host.slice(0, colon) : host).toLowerCase();+}++/**+ * HOST gate: loopback names, the bind literals (any port), the declared+ * `publicUrl` host (exact host[:port] after default-port normalization), and+ * the legacy tunnel host. Never widened by consent.+ */+export function isHostAdmitted(host: string | undefined, policy: IngressPolicy): boolean {+ if (isAllowedWorkspaceHostHeader(host)) return true;+ if (host === undefined) return false;+ if (policy.bindLiterals.length > 0) {+ const hostname = hostnameOfHostHeader(host);+ if (hostname !== null && policy.bindLiterals.includes(hostname)) return true;+ }+ if (+ policy.publicOrigin !== undefined &&+ hostHeaderMatchesPublicHost(host, policy.publicOrigin.host)+ ) {+ return true;+ }+ return (+ policy.legacyRemote !== undefined &&+ hostHeaderMatchesPublicHost(host, policy.legacyRemote.publicHost)+ );+}++/**+ * ORIGIN gate ("if present, must match" — callers skip when absent): the+ * loopback/null/file:// set, the legacy tunnel origin (https), the declared+ * public origin (scheme-matched against `publicUrl`'s own scheme), and the+ * bind literals over http or https.+ */+export function isOriginAdmitted(origin: string, policy: IngressPolicy): boolean {+ if (isAllowedApiOrigin(origin, policy.legacyRemote?.publicHost)) return true;+ let parsed: URL;+ try {+ parsed = new URL(origin);+ } catch {+ return false;+ }+ if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;+ if (+ policy.publicOrigin !== undefined &&+ parsed.protocol === policy.publicOrigin.protocol &&+ normalizeHostHeader(parsed.host) === policy.publicOrigin.host+ ) {+ return true;+ }+ if (policy.bindLiterals.length > 0) {+ const hostname = normalizeBindLiteral(parsed.hostname);+ if (policy.bindLiterals.includes(hostname)) return true;+ }+ return false;+}++/**+ * Tripwire: proxy-forwarding headers on a request when the policy does not+ * tolerate them — a tunnel/proxy points at a server that never opted into+ * exposure. Callers refuse with the fix instruction.+ */+export function tripsForwardedHeaderTripwire(+ req: Pick<IncomingMessage, 'headers'>,+ policy: IngressPolicy,+): boolean {+ return !policy.tolerateForwardedHeaders && hasForwardingHeaders(req);+}++/**+ * Per-request ingress context, stamped once at admission — by the `/api/*`+ * pipeline for HTTP and by the collaboration host for WS upgrades — so both+ * halves of the server carry the same actor-bearing shape. `actor` is the+ * auth drop-in point: today every admitted request is the anonymous+ * local-owner surface (`undefined`); a future authentication layer resolves+ * a principal here at the one chokepoint instead of per route.+ */+export interface IngressRequestContext {+ /** Correlation id when the surface resolves one (HTTP `/api/*` only). */+ requestId: string | undefined;+ /** TCP-peer classification at admission time. */+ peerClass: 'loopback' | 'external' | 'unknown';+ /** Authenticated principal — always `undefined` until auth is un-deferred. */+ actor: undefined;+}++const ingressContexts = new WeakMap<IncomingMessage, IngressRequestContext>();++export function stampIngressContext(+ req: IncomingMessage,+ input: { requestId?: string | undefined },+): IngressRequestContext {+ const peer = req.socket?.remoteAddress;+ const context: IngressRequestContext = {+ requestId: input.requestId,+ peerClass: peer === undefined ? 'unknown' : isLoopbackAddress(peer) ? 'loopback' : 'external',+ actor: undefined,+ };+ ingressContexts.set(req, context);+ return context;+}++export function getIngressContext(req: IncomingMessage): IngressRequestContext | undefined {+ return ingressContexts.get(req);+}diff --git a/packages/server/src/local-op-security.test.ts b/packages/server/src/local-op-security.test.tsindex d112d026c..bd2d6b047 100644--- a/packages/server/src/local-op-security.test.ts+++ b/packages/server/src/local-op-security.test.ts@@ -14,6 +14,7 @@ import { afterAll, beforeAll, describe, expect, test, vi } from 'vitest';const realpathSyncMock = vi.fn();const lstatSyncMock = vi.fn();let realFs: typeof import('node:fs');+let buildIngressPolicy: typeof import('./ingress-policy.ts').buildIngressPolicy;let checkLocalOpSecurity: typeof import('./local-op-security.ts').checkLocalOpSecurity;let createConcurrencyGuard: typeof import('./local-op-security.ts').createConcurrencyGuard;let hasValidLocalOpOrigin: typeof import('./local-op-security.ts').hasValidLocalOpOrigin;@@ -40,6 +41,7 @@ beforeAll(async () => {isPathWithinHome,isSafeLocalPath,} = await import('./local-op-security.ts'));+ ({ buildIngressPolicy } = await import('./ingress-policy.ts'));});function overrideRealpathSync(impl: typeof fs.realpathSync): { mockRestore: () => void } {@@ -717,22 +719,51 @@ describe('hasValidLocalOpOrigin with a remote public host', () => {const reqWithOrigin = (origin: string) =>({ headers: { origin }, socket: { remoteAddress: '127.0.0.1' } }) as never;- test('admits the https tunnel origin only when the host is supplied', () => {+ const tunnelPolicy = () =>+ buildIngressPolicy({+ remoteAccess: {+ url: 'https://myproject.ngrok.app',+ publicHost: 'myproject.ngrok.app',+ port: 24_550,+ },+ });++ test('admits the https tunnel origin only when the policy carries it', () => {expect(- hasValidLocalOpOrigin(reqWithOrigin('https://myproject.ngrok.app'), 'myproject.ngrok.app'),+ hasValidLocalOpOrigin(reqWithOrigin('https://myproject.ngrok.app'), tunnelPolicy()),).toBe(true);expect(hasValidLocalOpOrigin(reqWithOrigin('https://myproject.ngrok.app'))).toBe(false);});- test('still refuses foreign origins with the host supplied', () => {- expect(- hasValidLocalOpOrigin(reqWithOrigin('https://evil.example.com'), 'myproject.ngrok.app'),- ).toBe(false);+ test('still refuses foreign origins with the tunnel policy supplied', () => {+ expect(hasValidLocalOpOrigin(reqWithOrigin('https://evil.example.com'), tunnelPolicy())).toBe(+ false,+ );});test('loopback origins keep working alongside the remote host', () => {- expect(- hasValidLocalOpOrigin(reqWithOrigin('http://localhost:5173'), 'myproject.ngrok.app'),- ).toBe(true);+ expect(hasValidLocalOpOrigin(reqWithOrigin('http://localhost:5173'), tunnelPolicy())).toBe(+ true,+ );+ });++ test('a bind-literal origin admits over http/https only — parity with isOriginAdmitted', () => {+ const bound = buildIngressPolicy({+ serverRuntime: {+ port: undefined,+ bind: ['100.64.0.7'],+ publicUrl: undefined,+ publicUrlSource: undefined,+ allowExternal: true,+ openBrowser: false,+ idleShutdown: 'off',+ loopbackOnly: false,+ },+ });+ expect(hasValidLocalOpOrigin(reqWithOrigin('http://100.64.0.7:55222'), bound)).toBe(true);+ expect(hasValidLocalOpOrigin(reqWithOrigin('https://100.64.0.7'), bound)).toBe(true);+ // A non-http(s) scheme on the same bind literal must be refused, exactly+ // as isOriginAdmitted refuses it — the two gates share one admitted set.+ expect(hasValidLocalOpOrigin(reqWithOrigin('ftp://100.64.0.7'), bound)).toBe(false);});});diff --git a/packages/server/src/local-op-security.ts b/packages/server/src/local-op-security.tsindex d749220e2..cc016feba 100644--- a/packages/server/src/local-op-security.ts+++ b/packages/server/src/local-op-security.ts@@ -18,6 +18,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:patimport { ALLOWED_GIT_TRANSPORTS } from '@inkeep/open-knowledge-core/skills-catalog';import { errorResponse } from './http/error-response.ts';import { errnoCode } from './http/handler-utils.ts';+import { buildIngressPolicy, type IngressPolicy, isPeerAdmitted } from './ingress-policy.ts';import { getLogger } from './logger.ts';import { originMatchesPublicHost } from './remote-access.ts';@@ -224,42 +225,72 @@ export function isLoopbackRequest(req: IncomingMessage): boolean {}/**- * Returns true if the Origin header (when present) is a loopback origin.- * Absent Origin header is allowed (same-origin browser requests / CLI tools).+ * Returns true if the Origin header (when present) is admitted. Absent Origin+ * header is allowed (same-origin browser requests / CLI tools).+ *+ * The admitted set beyond loopback comes from the ingress policy: the legacy+ * tunnel origin, the declared `publicUrl` origin (scheme-matched), and the+ * bind literals — an empty policy keeps the historical loopback-only set.** Parses the URL and compares hostname exactly; a raw `startsWith` would* accept crafted origins like `http://127.0.0.1.evil.com` if DNS rebinding* ever lined up with the loopback socket check.*/-export function hasValidLocalOpOrigin(req: IncomingMessage, remotePublicHost?: string): boolean {+export function hasValidLocalOpOrigin(req: IncomingMessage, policy?: IngressPolicy): boolean {const origin = req.headers.origin;if (!origin) return true;- // Remote mode: the SPA served through the tunnel fetches from its public- // origin — admitted alongside the loopback set. Absent (local mode), the- // allowlist stays loopback-only.- if (remotePublicHost !== undefined && originMatchesPublicHost(origin, remotePublicHost)) {+ const legacyHost = policy?.legacyRemote?.publicHost;+ if (legacyHost !== undefined && originMatchesPublicHost(origin, legacyHost)) {return true;}try {// WHATWG URL preserves the IPv6 brackets in `hostname` (e.g. `[::1]`), so// the comparison set includes the bracketed form alongside the literal.- const { hostname } = new URL(origin);- return (+ const url = new URL(origin);+ const { hostname } = url;+ if (hostname === '127.0.0.1' ||hostname === 'localhost' ||hostname === '[::1]' ||hostname === '::1'- );+ ) {+ return true;+ }+ if (policy === undefined) return false;+ if (+ policy.publicOrigin !== undefined &&+ url.protocol === policy.publicOrigin.protocol &&+ normalizeOriginHost(url.host) === policy.publicOrigin.host+ ) {+ return true;+ }+ // Bind-literal origins admit over http/https only — parity with+ // `isOriginAdmitted`, so the two halves of the one policy agree on the+ // admitted set. Without the scheme guard a non-browser client's+ // `ftp://<bind-ip>` (or any custom scheme) would pass here while the same+ // origin is refused on /api and /mcp.+ if (url.protocol !== 'http:' && url.protocol !== 'https:') return false;+ const bare = hostname.startsWith('[') ? hostname.slice(1, -1) : hostname;+ return policy.bindLiterals.includes(bare.toLowerCase());} catch {return false;}}+/** Strip a default-port suffix — mirrors `normalizeHostHeader` in remote-access.ts. */+function normalizeOriginHost(host: string): string {+ return host.replace(/:(443|80)$/, '').toLowerCase();+}+/**- * Convenience wrapper: runs loopback + origin checks, emits an RFC 9457 403+ * Convenience wrapper: runs peer + origin checks, emits an RFC 9457 403* problem+json response if either fails, and returns false. Returns* true when the request is allowed.*+ * The peer arm is the policy's: loopback always passes, and+ * `server.allowExternal` is the sanctioned relaxation — local-op endpoints+ * are part of the owner surface the deployer's edge admits.+ ** The two failure modes use distinct URN tokens so operators can route on* the typed `problem.type`: `urn:ok:error:loopback-required` (network-level)* vs `urn:ok:error:invalid-origin` (header-level). `handler` is the@@ -268,9 +299,10 @@ export function hasValidLocalOpOrigin(req: IncomingMessage, remotePublicHost?: sexport function checkLocalOpSecurity(req: IncomingMessage,res: ServerResponse,- options: { handler: string; remotePublicHost?: string },+ options: { handler: string; policy?: IngressPolicy },): boolean {- if (!isLoopbackRequest(req)) {+ const policy = options.policy ?? buildIngressPolicy({});+ if (!isLoopbackRequest(req) && !isPeerAdmitted(req.socket.remoteAddress, policy)) {errorResponse(res,403,@@ -280,7 +312,7 @@ export function checkLocalOpSecurity();return false;}- if (!hasValidLocalOpOrigin(req, options.remotePublicHost)) {+ if (!hasValidLocalOpOrigin(req, policy)) {errorResponse(res,403,diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.tsindex d4d8c4ee7..8b6d41a41 100644--- a/packages/server/src/mcp-mount.ts+++ b/packages/server/src/mcp-mount.ts@@ -28,7 +28,6 @@ import type { AcpThreadManager } from './acp/thread-manager.ts';import type { AgentFocusBroadcaster } from './agent-focus.ts';import type { AgentPresenceBroadcaster } from './agent-presence.ts';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 {@@ -37,11 +36,17 @@ import {type HealthProvider,type NativeApiHandle,} from './http/http-app.ts';+import {+ buildIngressPolicy,+ type IngressPolicy,+ isHostAdmitted,+ isOriginAdmitted,+ isPeerAdmitted,+ tripsForwardedHeaderTripwire,+} from './ingress-policy.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, type ResolvedRemoteAccess } from './remote-access.ts';export type { ReadinessState } from './http/http-app.ts';@@ -151,19 +156,13 @@ export interface MountMcpAndApiOptions {*/nativeApi: NativeApiHandle | undefined;/**- * Resolved `remote:` config (null/undefined ⇒ remote access disabled).- * When set, EVERY surface (`/mcp`, `/api/*`, `/collab`, content assets,- * the SPA) admits requests whose Host is either a loopback name or the- * tunnel's public host — the trust-the-tunnel model: OK does not- * authenticate remote callers, the tunnel's edge does (see- * `remote-access.ts`). Wrong-Host requests (DNS-rebound pages) are refused.- * Local loopback behavior is byte-for-byte unchanged.- *- * When null/undefined, requests carrying proxy-forwarding headers are- * refused with a hint — a tunnel pointed at a server that never opted in- * must fail loud, not silently inherit full local trust.+ * The boot-built ingress policy — ONE admission shape for every surface+ * (`/mcp`, `/api/*`, `/collab` upgrades, content assets, the SPA): peer,+ * Host, and Origin predicates plus the proxied-request tripwire (see+ * `ingress-policy.ts`). Omitted (test rigs, dev-server plugin) ⇒ the+ * loopback-only default policy, byte-for-byte today's local behavior.*/- remoteAccess?: ResolvedRemoteAccess | null;+ ingressPolicy?: IngressPolicy;}export interface MountMcpAndApiHandle {@@ -210,7 +209,7 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandlreactShellMiddleware,ephemeral,} = opts;- const remoteAccess = opts.remoteAccess ?? undefined;+ const ingressPolicy = opts.ingressPolicy ?? buildIngressPolicy({});const collaborationHost = createCollaborationHost({hocuspocus,@@ -221,7 +220,7 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandlmaintenanceCoordinator,keepaliveGraceMs: opts.keepaliveGraceMs,acpThreadManager: opts.acpThreadManager,- remoteAccess,+ ingressPolicy,});const onRequest = (req: IncomingMessage, res: ServerResponse): void => {@@ -230,30 +229,29 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl// 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 (!admitRequestSurface(req, res, ingressPolicy, 'mcp-mount')) return;if (mcpHttpHandler !== undefined && url === '/mcp') {const origin = req.headers.origin;const sessionId = Array.isArray(req.headers['mcp-session-id'])? req.headers['mcp-session-id'][0]: req.headers['mcp-session-id'];- if (remoteAccess === undefined) {- // The pre-remote gate pair, unchanged: loopback socket + loopback- // Host. (With remote enabled the shared admit gate above already- // enforced the superset.)- if (!isLoopbackAddress(req.socket.remoteAddress)) {+ if (ingressPolicy.legacyRemote === undefined) {+ // The policy's peer + Host gate pair. (With legacy remote armed the+ // shared admit gate above already enforced the superset.)+ if (!isPeerAdmitted(req.socket.remoteAddress, ingressPolicy)) {errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback access required.', {handler: 'mcp',});return;}- if (!isAllowedWorkspaceHostHeader(req.headers.host)) {+ if (!isHostAdmitted(req.headers.host, ingressPolicy)) {errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {handler: 'mcp',});return;}}- if (origin !== undefined && !isAllowedApiOrigin(origin, remoteAccess?.publicHost)) {+ if (origin !== undefined && !isOriginAdmitted(origin, ingressPolicy)) {errorResponse(res, 403, 'urn:ok:error:invalid-origin', 'Origin not allowed.', {handler: 'mcp',});@@ -357,17 +355,17 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl};const runContent = (onMiss: () => void): void => {// Ephemeral single-file mode serves assets out of the opened file's- // parent dir; mirror the `/mcp` loopback + workspace-host gate so a- // DNS-rebound or non-loopback caller can't read that user-data dir.- // Origin is intentionally NOT checked: no-cors `<img>` / CSS asset loads- // omit it, and the Host-header check already rejects the rebinding+ // parent dir; mirror the `/mcp` peer + Host gate so a DNS-rebound or+ // non-admitted caller can't read that user-data dir. Origin is+ // intentionally NOT checked: no-cors `<img>` / CSS asset loads omit+ // it, and the Host-header check already rejects the rebinding// content-exfil vector without that dependency. Project / desktop modes// (`ephemeral` falsy) are unchanged — the user chose the served root.if (ephemeral === true &&contentAssetMiddleware !== undefined &&- (!isLoopbackAddress(req.socket.remoteAddress) ||- !isAllowedWorkspaceHostHeader(req.headers.host))+ (!isPeerAdmitted(req.socket.remoteAddress, ingressPolicy) ||+ !isHostAdmitted(req.headers.host, ingressPolicy))) {errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback access required.', {handler: 'content-asset',@@ -428,10 +426,10 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandlconst onUpgrade = (req: IncomingMessage, socket: Duplex, head: Buffer): void => {if (collaborationHost.handleUpgrade(req, socket, head)) return;- if (remoteAccess === undefined && hasForwardingHeaders(req)) {+ if (tripsForwardedHeaderTripwire(req, ingressPolicy)) {log.warn({ url: req.url, host: req.headers.host },- '[remote] refused proxied WS upgrade; start the server with `ok start --remote <url>`',+ '[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_PUBLIC_URL, or start with `ok start --remote <url>`',);}socket.destroy();@@ -444,7 +442,7 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandlconst { requestListener } = createHttpApp({health: opts.health,nativeApi: opts.nativeApi,- remoteAccess,+ ingressPolicy,legacyDispatch: onRequest,log,});diff --git a/packages/server/src/remote-access.ts b/packages/server/src/remote-access.tsindex 88d38b4d0..00e438fcc 100644--- a/packages/server/src/remote-access.ts+++ b/packages/server/src/remote-access.ts@@ -64,7 +64,7 @@ function firstHeader(value: string | string[] | undefined): string | undefined {}/** Strip a default-port suffix so `host:443`/`host:80` compare equal to `host`. */-function normalizeHostHeader(host: string): string {+export function normalizeHostHeader(host: string): string {return host.replace(/:(443|80)$/, '').toLowerCase();}@@ -106,9 +106,13 @@ export function isRemoteAdmitted(const FORWARDING_HEADERS = ['x-forwarded-for','x-forwarded-proto',+ 'x-forwarded-host','forwarded','x-real-ip',+ 'x-client-ip',+ 'x-cluster-client-ip','cf-connecting-ip',+ 'fastly-client-ip','true-client-ip',] as const;diff --git a/packages/server/src/remote-mcp.test.ts b/packages/server/src/remote-mcp.test.tsindex 85e380039..b6ad5d822 100644--- a/packages/server/src/remote-mcp.test.ts+++ b/packages/server/src/remote-mcp.test.ts@@ -28,6 +28,7 @@ import { join } from 'node:path';import type { Hocuspocus } from '@hocuspocus/server';import { afterEach, describe, expect, test } from 'vitest';import { ConfigSchema } from './config/schema.ts';+import { buildIngressPolicy } from './ingress-policy.ts';import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';import { createMcpHttpHandler, type McpHttpHandler } from './mcp-http.ts';import { type MountMcpAndApiHandle, mountMcpAndApi } from './mcp-mount.ts';@@ -104,7 +105,7 @@ async function bootRemoteRig(nativeApi: undefined,hocuspocus,mcpHttpHandler: handler,- remoteAccess,+ ingressPolicy: buildIngressPolicy({ remoteAccess }),...(extras.reactShellMiddleware ? { reactShellMiddleware: extras.reactShellMiddleware } : {}),...(extras.acpThreadManager !== undefined? { acpThreadManager: extras.acpThreadManager as never }diff --git a/packages/server/src/server-factory.test.ts b/packages/server/src/server-factory.test.tsindex aa5d32bef..cdd499a62 100644--- a/packages/server/src/server-factory.test.ts+++ b/packages/server/src/server-factory.test.ts@@ -29,6 +29,7 @@ import type {ProbeTokenStore,PushPermission,} from './github-permissions.ts';+import { buildIngressPolicy } from './ingress-policy.ts';import { loggerFactory, type PinoLogger } from './logger.ts';import {createManagedRenameRecoveryJournal,@@ -2725,7 +2726,13 @@ describe('createServer() — config-doc admission guard', () => {contentDir: tmpDir,projectDir: tmpDir,quiet: true,- remotePublicHost: 'myproject.ngrok.app',+ ingressPolicy: buildIngressPolicy({+ remoteAccess: {+ url: 'https://myproject.ngrok.app',+ publicHost: 'myproject.ngrok.app',+ port: 24_550,+ },+ }),});try {await server.ready;diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex 2a2fd4585..8cab15ab4 100644--- a/packages/server/src/server-factory.ts+++ b/packages/server/src/server-factory.ts@@ -138,9 +138,14 @@ import { errnoCode } from './http/handler-utils.ts';import type { NativeApiHandle } from './http/http-app.ts';import type { LocalApiDispatch } from './http/local-api-dispatch.ts';import { scanGlobalInPlaceSkills, scanInPlaceSkillDirs } from './in-place-skills.ts';+import {+ buildIngressPolicy,+ type IngressPolicy,+ isHostAdmitted,+ isPeerAdmitted,+} from './ingress-policy.ts';import { createLiveDerivedIndexExtension } from './live-derived-index.ts';import { getLogger } from './logger.ts';-import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';import { LossCaptureRing } from './loss-capture.ts';import {createMaintenanceCoordinator,@@ -177,7 +182,6 @@ import {import { loadPrincipal } from './principal.ts';import { RecentlyRemovedDocs } from './recently-removed-docs.ts';import { reconcile } from './reconciliation.ts';-import { hostHeaderMatchesPublicHost } from './remote-access.ts';import { runRemovalRedirectGuard } from './removal-redirect-guard.ts';import { loadRemovedDocsJournal, saveRemovedDocsJournal } from './removed-docs-journal.ts';import {@@ -221,11 +225,12 @@ import { cleanupOrphanUploadTempfiles } from './upload-streaming.ts';export interface ServerOptions {/**- * The tunnel's public host when remote access is enabled — threaded into- * the API extension so the browser-Origin allowlists admit the remote- * SPA's origin. See `ApiExtensionOptions.remotePublicHost`.+ * The boot-built ingress policy — threaded into the API extension and the+ * config-doc admission guard so every peer/Host/Origin decision consults+ * the one policy object. Omitted (test rigs, dev-server plugin) ⇒ the+ * loopback-only default policy.*/- remotePublicHost?: string;+ ingressPolicy?: IngressPolicy;port?: number;host?: string;contentDir: string;@@ -657,6 +662,7 @@ export function createServer(options: ServerOptions): ServerInstance {// cert. Idempotent — covers every server-launch path (utility fork, detached,// in-process) from one place; the CLI and desktop-main processes call it too.trustSystemCertificates();+ const ingressPolicy = options.ingressPolicy ?? buildIngressPolicy({});const {contentDir,projectDir = contentDir,@@ -1875,7 +1881,7 @@ export function createServer(options: ServerOptions): ServerInstance {headers?: { host?: string };};const peer = req.socket?.remoteAddress;- if (peer !== undefined && !isLoopbackAddress(peer)) {+ if (peer !== undefined && !isPeerAdmitted(peer, ingressPolicy)) {logAuthRejection('config-doc-admission-denied', payload.documentName, { check: 'peer' });throw new Error(`config-doc admission requires loopback peer (peer=${peer}, doc=${payload.documentName})`,@@ -1892,10 +1898,7 @@ export function createServer(options: ServerOptions): ServerInstance {(headersBag && typeof headersBag.get === 'function' ? headersBag.get('host') : null) ??req.headers?.host ??undefined;- const remoteHostOk =- options.remotePublicHost !== undefined &&- hostHeaderMatchesPublicHost(host, options.remotePublicHost);- if (!isAllowedWorkspaceHostHeader(host) && !remoteHostOk) {+ if (!isHostAdmitted(host, ingressPolicy)) {logAuthRejection('config-doc-admission-denied', payload.documentName, { check: 'host' });throw new Error(`config-doc admission requires a loopback or remote Host header (host=${host ?? '<absent>'}, doc=${payload.documentName})`,@@ -2008,7 +2011,7 @@ export function createServer(options: ServerOptions): ServerInstance {const apiExtension = createApiExtension({hocuspocus,durabilityState,- remotePublicHost: options.remotePublicHost,+ ingressPolicy,sessionManager,commentDocHooksRef,contentDir,