Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.md
new file mode 100644
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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-ins
attachUiSibling,
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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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)[]): unkno
const 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.ts
index 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.ts
index 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): ServerRu
const 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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): Coll
maintenanceCoordinator,
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): Coll
wss.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): Coll
acpThreadManager === 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): Coll
handleKeepalive(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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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:pat
import { 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?: s
export 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.ts
index 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): MountMcpAndApiHandl
reactShellMiddleware,
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): MountMcpAndApiHandl
maintenanceCoordinator,
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): MountMcpAndApiHandl
const 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): MountMcpAndApiHandl
const { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,