Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): make server.bind per-machine to protect local clones (#3500)

omar-inkeepabc145e4be56
diff --git a/.changeset/server-bind-per-machine.md b/.changeset/server-bind-per-machine.md
new file mode 100644
index 000000000..b7c20cc03
--- /dev/null
+++ b/.changeset/server-bind-per-machine.md
@@ -0,0 +1,11 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+`server.bind` is now a per-machine setting, so a committed bind can no longer break local runs for people who clone a shared project.
+
+Before this change, a project that committed `server.bind: 0.0.0.0` (or `::`) to `.ok/config.yml` so one machine could serve it remotely made `ok start` fail for every teammate who cloned the repo and ran it locally. The exposure interlock refused to boot because a non-loopback bind requires per-machine `server.allowExternal` consent, and consent is never committed.
+
+`server.bind` moves from `project` scope to `project-local`, the same posture as `server.allowExternal`. A bind committed to the shared `.ok/config.yml` is now ignored, and named at startup with the fix, so local clones always bind loopback and boot. The machine that actually exposes the server sets the bind per-machine with `OK_BIND`, `ok start --bind <address>`, or `.ok/local/config.yml`.
+
+The exposure gate is unchanged: an explicit `OK_BIND` or `--bind` to a non-loopback address without consent still refuses to start.
diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdx
index cd12d81db..beeb77236 100644
--- a/docs/content/reference/configuration.mdx
+++ b/docs/content/reference/configuration.mdx
@@ -47,7 +47,7 @@ A key set in a file more specific than its scope (a user-scope key in `.ok/confi
| `autoSync.mode` | `"off" \| "follow" \| "full" \| null` | `null` | project-local | Per-machine sync mode for this project: `off` (no sync), `follow` (one-directional — pull remote changes, never push your own; the earlier value `pull` is accepted as an alias), `full` (bidirectional pull and push). `null` means "unanswered"; the editor's onboarding modal triggers on first remote-detected open. Supersedes `autoSync.enabled`. |
| `autoSync.enabled` | `boolean \| null` | `null` | project-local | Legacy per-machine auto-sync toggle, superseded by `autoSync.mode`. Read only when `mode` is absent (`true` = full, `false` = off). `null` means "unanswered". |
| `autoSync.default` | `"off" \| "follow" \| "full" \| boolean \| null` | `null` | project | Committed seed for each machine's first-open sync mode: `off` / `follow` / `full`, or the legacy boolean (`true` = full, `false` = off). `null` = ask. Lets a maintainer pre-answer the onboarding prompt for everyone who clones; a per-machine `autoSync.mode` overrides it. Compatibility note: a committed string value (`off` / `follow` / `full`) is rejected by app versions released before `autoSync.mode` existed, resetting that machine to config defaults until it updates (it never silently syncs). The legacy boolean seed (`true` / `false`) stays readable by older apps — commit `follow` only once collaborators are on a current version. |
-| `server.bind` | list of addresses | `["127.0.0.1"]` | project | Addresses the server binds, e.g. `[127.0.0.1]` or `[0.0.0.0]`. The loopback default keeps everything off-machine out. A non-loopback bind additionally requires the `server.allowExternal` consent interlock. Lists replace, never merge. Env: `OK_BIND` (space-separated). Read at server start. |
+| `server.bind` | list of addresses | `["127.0.0.1"]` | project-local | Addresses the server binds, e.g. `[127.0.0.1]` or `[0.0.0.0]`. The loopback default keeps everything off-machine out. A non-loopback bind additionally requires the `server.allowExternal` consent interlock. Per-machine — a value committed to `.ok/config.yml` is ignored (the exposing host would otherwise refuse to boot for every teammate who clones and runs locally, since the interlock needs per-machine consent that is never committed). Set it where the server is exposed: `OK_BIND` (space-separated), `ok start --bind <address>`, or `.ok/local/config.yml`. Lists replace, never merge. Read at server start. |
| `server.port` | number | (unset) | project | TCP port the server listens on. Unset = a local start picks a free port dynamically (deployment platforms inject `PORT` instead). Supersedes `remote.port`, which is still read while this key is absent. Read at server start. |
| `server.externalUrl` | string | (unset) | project | Canonical external origin the server is reached at, e.g. `https://kb.example.com` — its host joins the Host/Origin allowlists and issued URLs. Setting it declares external exposure, which additionally requires the `server.allowExternal` consent interlock. Supersedes `server.publicUrl` (the key's former name — still read as a deprecated alias while this key is absent) and `remote.url`. Env: `OK_EXTERNAL_URL` (`OK_PUBLIC_URL` remains a deprecated alias); flag: `ok start --external-url <url>`. Read at server start. Compatibility note: app versions from before this key existed read only `server.publicUrl` and silently ignore `server.externalUrl` (config is open-shape), so committing only the new key drops the declared host from those versions' Host/Origin allowlists and external requests 403. While collaborators are still on older versions, commit **both** keys with the same value — current versions prefer `server.externalUrl` (no deprecation notice when both are set) and older versions keep reading `server.publicUrl`; drop the old key once everyone has upgraded. |
| `server.publicUrl` | string | (unset) | project | Deprecated alias of `server.externalUrl` (the key's former name) — read only while that key is absent, with identical semantics; the CLI prints a rename notice when it is the one in effect. Env alias: `OK_PUBLIC_URL`; flag alias: `ok start --public-url <url>`. May be committed alongside `server.externalUrl` during a mixed-version window (see that key's compatibility note). Slated for removal after a deprecation window. |
diff --git a/packages/cli/src/cli.test.ts b/packages/cli/src/cli.test.ts
index 61d5f5aa7..ab10cc42a 100644
--- a/packages/cli/src/cli.test.ts
+++ b/packages/cli/src/cli.test.ts
@@ -1,4 +1,7 @@
-import { describe, expect, test } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
const CLI_PACKAGE_ROOT = import.meta.dir.replace(/\/src$/, '');
@@ -97,3 +100,56 @@ describe('CLI --version notice', () => {
expect(stdout).toMatch(/NO WARRANTY/);
}, 30_000);
});
+
+describe('committed project-local key startup warning', () => {
+ let projectDir: string;
+
+ beforeEach(() => {
+ projectDir = mkdtempSync(join(tmpdir(), 'ok-committed-bind-'));
+ mkdirSync(join(projectDir, '.ok'), { recursive: true });
+ // A committed non-loopback bind — the clone-breaking case. It resolves to
+ // the loopback default (ignored), and the preAction hook must name it.
+ writeFileSync(join(projectDir, '.ok', 'config.yml'), 'server:\n bind:\n - 0.0.0.0\n');
+ });
+
+ afterEach(() => {
+ rmSync(projectDir, { recursive: true, force: true });
+ });
+
+ test('the preAction hook names a committed server.bind as ignored and points at the OK_BIND fix', () => {
+ // Exercises the wired emission loop in cli.ts — the loader-level and
+ // formatter-level unit tests both pass even if this glue is removed, so a
+ // command that goes through the preAction hook (`ok ps`) is the surface that
+ // proves the startup warning actually reaches stderr.
+ const result = Bun.spawnSync({
+ cmd: [
+ 'node',
+ '--import',
+ 'tsx',
+ '--conditions=development',
+ '-e',
+ `
+ process.argv = [
+ process.execPath,
+ process.cwd() + '/src/cli.ts',
+ '--cwd',
+ ${JSON.stringify(projectDir)},
+ 'ps',
+ '--json',
+ ];
+ await import('./src/cli.ts');
+ `,
+ ],
+ cwd: CLI_PACKAGE_ROOT,
+ env: { ...process.env, NO_COLOR: '1' },
+ });
+
+ const stderr = result.stderr.toString();
+ expect(stderr).toContain('server.bind is a per-machine (project-local) setting');
+ expect(stderr).toContain('.ok/local/config.yml');
+ expect(stderr).toContain('OK_BIND');
+ // The committed value is IGNORED, not applied — nothing exposes, so the
+ // exposure interlock must never fire on this read-only listing.
+ expect(stderr).not.toContain('ExposureConsentError');
+ }, 30_000);
+});
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index b7bea6998..7ecf13014 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -21,7 +21,7 @@ trustSystemCertificates();
import { spawn } from 'node:child_process';
import { resolve } from 'node:path';
-import { humanFormat } from '@inkeep/open-knowledge-core';
+import { formatIgnoredCommittedKey, humanFormat } from '@inkeep/open-knowledge-core';
import { type Config, ConfigSchema, trustSystemCertificates } from '@inkeep/open-knowledge-server';
/**
* CLI entry point for @inkeep/open-knowledge.
@@ -169,6 +169,14 @@ program
console.error(`[ok] ${humanFormat(diagnostic)}`);
}
}
+ // Project-local keys committed to the shared `.ok/config.yml` are silently
+ // dropped by the scope-aware merge — a committed `server.bind` would
+ // otherwise refuse to boot for every teammate who clones and runs locally.
+ // Name each one and its per-machine fix, once per invocation, for every
+ // command (including the config family — nothing else reports these yet).
+ for (const key of loaded.ignoredCommittedKeys) {
+ console.error(`[ok] ${formatIgnoredCommittedKey(key)}`);
+ }
} catch (err) {
if (subcommandName === 'uninstall' || subcommandName === 'deinit') {
// Surface the original parse error before degrading — the user should
diff --git a/packages/cli/src/config/loader.test.ts b/packages/cli/src/config/loader.test.ts
index e4f847a31..8ad3e430e 100644
--- a/packages/cli/src/config/loader.test.ts
+++ b/packages/cli/src/config/loader.test.ts
@@ -2,7 +2,14 @@ import { mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
-import { type ConfigDiagnostic, REMOVED_KEYS } from '@inkeep/open-knowledge-core';
+import {
+ applyConfigOverlay,
+ type ConfigDiagnostic,
+ REMOVED_KEYS,
+ requiresExternalConsent,
+ resolveEnvConfigLayer,
+ resolveServerRuntimeConfig,
+} from '@inkeep/open-knowledge-core';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { stringify } from 'yaml';
@@ -623,10 +630,73 @@ describe('loadConfig — scope-aware layering (project-local)', () => {
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');
+ test('project layer still owns project-scoped server keys (port, externalUrl)', () => {
+ writeWorkspaceConfig('server:\n port: 8080\n externalUrl: https://kb.example.com\n');
const { config } = loadConfig(testDir);
- expect(config.server.bind).toEqual(['127.0.0.1', '100.64.0.7']);
+ expect(config.server.port).toBe(8080);
+ expect(config.server.externalUrl).toBe('https://kb.example.com');
+ });
+
+ test('a committed server.bind is ignored (clone-safety) and reported as an ignored committed key', () => {
+ // The footgun: a repo commits a non-loopback bind so one machine serves
+ // remotely; a teammate who clones and runs `ok start` locally must bind the
+ // loopback default (and boot), never inherit the committed value — which
+ // would trip the exposure interlock they never consented to.
+ writeWorkspaceConfig('server:\n bind:\n - 0.0.0.0\n');
+ const { config, ignoredCommittedKeys } = loadConfig(testDir);
+ expect(config.server.bind).toEqual(['127.0.0.1']);
+ const bindKey = ignoredCommittedKeys.find((k) => k.path.join('.') === 'server.bind');
+ expect(bindKey).toBeDefined();
+ expect(bindKey?.envVar).toBe('OK_BIND');
+ });
+
+ test('a project-local server.bind is honored, with no ignored-committed-key warning', () => {
+ writeLocalConfig('server:\n bind:\n - 0.0.0.0\n');
+ const { config, ignoredCommittedKeys } = loadConfig(testDir);
+ expect(config.server.bind).toEqual(['0.0.0.0']);
+ expect(ignoredCommittedKeys).toEqual([]);
+ });
+
+ test('a committed file with both a removed key and a project-local key reports each correctly', () => {
+ // strip-removed-keys runs BEFORE the project-local detector in loadRawLayer.
+ // Pin that the two don't interfere: the removed `server.host` is stripped and
+ // reported as REMOVED_KEY, the committed `server.bind` survives stripping and
+ // is still flagged as ignored, and the in-scope `server.port` takes effect.
+ writeWorkspaceConfig('server:\n host: 0.0.0.0\n bind:\n - 0.0.0.0\n port: 8080\n');
+ const { config, diagnostics, ignoredCommittedKeys } = loadConfig(testDir);
+ expect(config.server.port).toBe(8080);
+ expect(config.server.bind).toEqual(['127.0.0.1']);
+ expect(removedKeys(diagnostics).some((k) => k.dotted === 'server.host')).toBe(true);
+ const bindKey = ignoredCommittedKeys.find((k) => k.path.join('.') === 'server.bind');
+ expect(bindKey).toBeDefined();
+ expect(bindKey?.envVar).toBe('OK_BIND');
+ });
+
+ test('interlock resolution: a committed bind boots on loopback, but explicit OK_BIND stays exposing', () => {
+ // Mirrors the `ok start` resolution pipeline: loadConfig (scope-aware merge)
+ // -> env overlay -> resolveServerRuntimeConfig. A committed non-loopback
+ // bind resolves loopback-only, so the exposure interlock passes and the
+ // server boots. The SAME value supplied per-machine via OK_BIND resolves
+ // non-loopback (loopbackOnly false, no consent) -> the interlock still
+ // refuses. That path is the real exposing host and must stay loud.
+ writeWorkspaceConfig('server:\n bind:\n - 0.0.0.0\n');
+ const { config } = loadConfig(testDir);
+
+ const committedRuntime = resolveServerRuntimeConfig(config);
+ expect(committedRuntime.bind).toEqual(['127.0.0.1']);
+ expect(committedRuntime.loopbackOnly).toBe(true);
+ // The interlock decision itself, not just its input: no consent required.
+ expect(requiresExternalConsent(committedRuntime)).toBe(false);
+
+ const envLayer = resolveEnvConfigLayer({ OK_BIND: '0.0.0.0' });
+ const envConfig = applyConfigOverlay(config, envLayer.layer) as typeof config;
+ const envRuntime = resolveServerRuntimeConfig(envConfig);
+ expect(envRuntime.bind).toEqual(['0.0.0.0']);
+ expect(envRuntime.loopbackOnly).toBe(false);
+ expect(envRuntime.allowExternal).toBe(false);
+ // The interlock still refuses: consent is required and not granted, so the
+ // exposing OK_BIND host stays loud (asserts the predicate, not just inputs).
+ expect(requiresExternalConsent(envRuntime)).toBe(true);
});
test('schema-invalid project-local file throws loud with the file named', () => {
diff --git a/packages/cli/src/config/loader.ts b/packages/cli/src/config/loader.ts
index 78d16b178..1462c14f9 100644
--- a/packages/cli/src/config/loader.ts
+++ b/packages/cli/src/config/loader.ts
@@ -36,8 +36,10 @@ import {
type ConfigDiagnostic,
type ConfigIssue,
type ConfigValidationError,
+ detectCommittedProjectLocalKeys,
detectRemovedKeys,
humanFormat,
+ type IgnoredCommittedKey,
locateIssue,
mergeLayered,
stripRemovedKeys,
@@ -65,6 +67,15 @@ export interface LoadConfigResult {
* without saying so reads as a silent data loss.
*/
sidelined: Array<{ from: string; to: string }>;
+ /**
+ * Project-local settings found in the committed `.ok/config.yml`, where
+ * `mergeLayered` silently drops them. Surfaced so the caller can warn once
+ * per invocation that the committed value is ignored and name the per-machine
+ * fix (`.ok/local/config.yml` / `OK_*`). The canonical offender is a
+ * committed `server.bind` that would otherwise refuse to boot for cloners.
+ * Empty when the committed layer sets nothing out of scope.
+ */
+ ignoredCommittedKeys: IgnoredCommittedKey[];
}
/** Short TTL for per-cwd config resolution in long-lived MCP sessions. */
@@ -179,6 +190,7 @@ export function loadConfig(cwd?: string): LoadConfigResult {
const sources: string[] = [];
const diagnostics: ConfigDiagnostic[] = [];
const sidelined: Array<{ from: string; to: string }> = [];
+ const ignoredCommittedKeys: IgnoredCommittedKey[] = [];
// Layer 1: user-global config — go through readConfigSafely so removed keys
// are stripped-and-reported and a genuinely broken file is sidelined; either
@@ -206,7 +218,11 @@ export function loadConfig(cwd?: string): LoadConfigResult {
// 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> => {
+ // `isCommittedLayer` is true only for the shared project file. Project-local
+ // keys belong in the gitignored local layer, so a project-local value there
+ // (or in the user layer) is expected — only a committed one is the ignored
+ // misconfiguration this reports.
+ const loadRawLayer = (filePath: string, isCommittedLayer = false): Record<string, unknown> => {
const file = loadYamlFile(filePath);
if (file.diagnostic !== undefined) {
diagnostics.push(file.diagnostic);
@@ -220,11 +236,22 @@ export function loadConfig(cwd?: string): LoadConfigResult {
});
diagnostics.push(...removedKeyDiagnostics);
sources.push(filePath);
- return removedKeyDiagnostics.length > 0 ? stripRemovedKeys(file.value) : file.value;
+ const value = removedKeyDiagnostics.length > 0 ? stripRemovedKeys(file.value) : file.value;
+ if (isCommittedLayer) {
+ ignoredCommittedKeys.push(
+ ...detectCommittedProjectLocalKeys({
+ value,
+ file: file.path,
+ source: file.source,
+ doc: file.doc,
+ }),
+ );
+ }
+ return value;
};
const projectPath = resolve(workingDir, OK_DIR, CONFIG_FILENAME);
- const projectRaw = loadRawLayer(projectPath);
+ const projectRaw = loadRawLayer(projectPath, true);
const localRaw = loadRawLayer(resolveConfigPath('project-local', workingDir));
// Scope-aware merge over the raw layers, then ONE parse fills defaults for
@@ -242,7 +269,7 @@ export function loadConfig(cwd?: string): LoadConfigResult {
const error: ConfigValidationError = { code: 'SCHEMA_INVALID', issues };
throw new Error(humanFormat(error));
}
- return { config: result.data, sources, diagnostics, sidelined };
+ return { config: result.data, sources, diagnostics, sidelined, ignoredCommittedKeys };
}
interface CreateProjectConfigResolverOptions {
diff --git a/packages/core/src/config/committed-scope-diagnostics.test.ts b/packages/core/src/config/committed-scope-diagnostics.test.ts
new file mode 100644
index 000000000..d6501b698
--- /dev/null
+++ b/packages/core/src/config/committed-scope-diagnostics.test.ts
@@ -0,0 +1,134 @@
+import { describe, expect, test } from 'vitest';
+import { parseDocument } from 'yaml';
+import {
+ detectCommittedProjectLocalKeys,
+ formatIgnoredCommittedKey,
+} from './committed-scope-diagnostics.ts';
+
+/** Dotted paths of the findings, sorted for order-independent assertions. */
+function paths(value: unknown): string[] {
+ return detectCommittedProjectLocalKeys({ value })
+ .map((f) => f.path.join('.'))
+ .sort();
+}
+
+describe('detectCommittedProjectLocalKeys', () => {
+ test('flags a committed server.bind — the clone-breaking case — with the OK_BIND fix', () => {
+ const findings = detectCommittedProjectLocalKeys({ value: { server: { bind: ['0.0.0.0'] } } });
+ expect(findings).toHaveLength(1);
+ expect(findings[0]?.path).toEqual(['server', 'bind']);
+ expect(findings[0]?.envVar).toBe('OK_BIND');
+ });
+
+ test('flags a committed loopback bind too — placement, not value, is the fault', () => {
+ // The whole point is that a committed bind is IGNORED regardless of value;
+ // a loopback one is harmless but still silently dropped, so name it.
+ expect(paths({ server: { bind: ['127.0.0.1'] } })).toEqual(['server.bind']);
+ });
+
+ test('flags committed exposure consent (server.allowExternal) with its env fix', () => {
+ const findings = detectCommittedProjectLocalKeys({
+ value: { server: { allowExternal: true } },
+ });
+ expect(findings).toHaveLength(1);
+ expect(findings[0]?.path).toEqual(['server', 'allowExternal']);
+ expect(findings[0]?.envVar).toBe('OK_ALLOW_EXTERNAL');
+ });
+
+ test('flags a project-local leaf with no env surface, and omits envVar', () => {
+ const findings = detectCommittedProjectLocalKeys({ value: { autoSync: { mode: 'full' } } });
+ expect(findings).toHaveLength(1);
+ expect(findings[0]?.path).toEqual(['autoSync', 'mode']);
+ expect(findings[0]?.envVar).toBeUndefined();
+ });
+
+ test('flags nested project-local leaves (search + sidebar)', () => {
+ expect(
+ paths({
+ search: { semantic: { enabled: true } },
+ appearance: { sidebar: { showHiddenFiles: true } },
+ }),
+ ).toEqual(['appearance.sidebar.showHiddenFiles', 'search.semantic.enabled']);
+ });
+
+ test('does NOT flag project-scope keys (the committed, shared shape)', () => {
+ expect(
+ paths({
+ content: { dir: 'docs' },
+ server: { port: 8080, externalUrl: 'https://kb.example.com' },
+ }),
+ ).toEqual([]);
+ });
+
+ test('does NOT flag user-scope keys', () => {
+ expect(paths({ slides: { enabled: true } })).toEqual([]);
+ });
+
+ test('ignores loose/unknown keys the schema does not register', () => {
+ expect(paths({ chrome: { totallyUnknown: 42 }, notAConfigKey: true })).toEqual([]);
+ });
+
+ test('separates ignored project-local keys from in-scope siblings in one pass', () => {
+ // A realistic mixed committed file: a shared content.dir + port (fine)
+ // alongside a bind + allowExternal that leaked in (ignored).
+ expect(
+ paths({
+ content: { dir: 'docs' },
+ server: { port: 8080, bind: ['0.0.0.0'], allowExternal: true },
+ }),
+ ).toEqual(['server.allowExternal', 'server.bind']);
+ });
+
+ test('non-object / empty input yields no findings', () => {
+ expect(detectCommittedProjectLocalKeys({ value: null })).toEqual([]);
+ expect(detectCommittedProjectLocalKeys({ value: 'nope' })).toEqual([]);
+ expect(detectCommittedProjectLocalKeys({ value: [] })).toEqual([]);
+ expect(detectCommittedProjectLocalKeys({ value: {} })).toEqual([]);
+ });
+
+ test('attaches source location when doc + source supplied', () => {
+ const source = 'server:\n bind:\n - 0.0.0.0\n';
+ const doc = parseDocument(source);
+ const findings = detectCommittedProjectLocalKeys({
+ value: doc.toJSON(),
+ file: '/tmp/.ok/config.yml',
+ source,
+ doc,
+ });
+ expect(findings).toHaveLength(1);
+ expect(findings[0]?.source?.file).toBe('/tmp/.ok/config.yml');
+ expect(findings[0]?.source?.line).toBeGreaterThanOrEqual(1);
+ });
+});
+
+describe('formatIgnoredCommittedKey', () => {
+ test('names the key, says it is ignored, and points at the per-machine fix + env var', () => {
+ const msg = formatIgnoredCommittedKey({ path: ['server', 'bind'], envVar: 'OK_BIND' });
+ expect(msg).toContain('server.bind');
+ expect(msg).toContain('ignored');
+ expect(msg).toContain('.ok/local/config.yml');
+ expect(msg).toContain('OK_BIND');
+ });
+
+ test('omits the env hint when the leaf has no env surface', () => {
+ const msg = formatIgnoredCommittedKey({ path: ['autoSync', 'mode'] });
+ expect(msg).toContain('autoSync.mode');
+ expect(msg).toContain('.ok/local/config.yml');
+ expect(msg).not.toContain('OK_');
+ });
+
+ test('prefixes file:line:column when the finding was source-located', () => {
+ const msg = formatIgnoredCommittedKey({
+ path: ['server', 'bind'],
+ envVar: 'OK_BIND',
+ source: { file: '/repo/.ok/config.yml', line: 3, column: 5 },
+ });
+ expect(msg.startsWith('/repo/.ok/config.yml:3:5: ')).toBe(true);
+ expect(msg).toContain('server.bind');
+ });
+
+ test('omits the location prefix when no source is attached', () => {
+ const msg = formatIgnoredCommittedKey({ path: ['server', 'bind'], envVar: 'OK_BIND' });
+ expect(msg.startsWith('server.bind')).toBe(true);
+ });
+});
diff --git a/packages/core/src/config/committed-scope-diagnostics.ts b/packages/core/src/config/committed-scope-diagnostics.ts
new file mode 100644
index 000000000..d69814093
--- /dev/null
+++ b/packages/core/src/config/committed-scope-diagnostics.ts
@@ -0,0 +1,117 @@
+/**
+ * Detect project-local settings that were committed to the shared project
+ * layer (`.ok/config.yml`), where they are silently ignored.
+ *
+ * `mergeLayered` skips the committed project layer for every project-local leaf
+ * (consent, per-machine listener + workflow knobs), so a value written there
+ * never reaches the running server — it resolves to the schema default or the
+ * user layer instead. That skip is a security + clone-safety feature (a
+ * committed `server.allowExternal` or `server.bind` can't arm exposure or break
+ * a teammate's local run), but it is also silent: the author believes the
+ * committed value took effect. This detector turns that silent no-op into a
+ * loud, source-located diagnostic so the value gets moved to where it works.
+ *
+ * The classic offender is `server.bind`: committing a non-loopback bind so one
+ * machine can serve remotely would otherwise refuse to boot for every teammate
+ * who clones the repo and runs it locally (the exposure interlock needs
+ * per-machine `allowExternal` consent that is never committed). Now a committed
+ * bind is inert AND named at start, with the OK_BIND / `.ok/local` fix.
+ *
+ * Pure introspection — no I/O. Keys off the field registry's `scope` metadata,
+ * exactly as `mergeLayered` does, so the two can never disagree about which
+ * leaves are project-local.
+ */
+
+import type { Document } from 'yaml';
+import { mechanicalEnvName, RECOGNIZED_ENV_VARS } from './env-layer.ts';
+import type { ConfigIssueSource } from './errors.ts';
+import { ConfigSchema } from './schema.ts';
+import { getLeafFieldMeta } from './schema-leaf.ts';
+import { locateIssue } from './source-locator.ts';
+
+/** A project-local leaf found in the committed project layer, where it is ignored. */
+export interface IgnoredCommittedKey {
+ /** Dotted-path segments of the ignored leaf, e.g. `['server', 'bind']`. */
+ path: string[];
+ /**
+ * The `OK_*` environment variable that sets this leaf per-machine, when one
+ * is ratified (e.g. `OK_BIND`). Absent for project-local leaves with no env
+ * surface — those move to `.ok/local/config.yml` only.
+ */
+ envVar?: string;
+ /** Source location in the committed file, when `file`/`source`/`doc` are supplied. */
+ source?: ConfigIssueSource;
+}
+
+export interface DetectCommittedProjectLocalKeysInput {
+ /** Raw committed project-layer value (pre-merge, pre-schema — the YAML projection). */
+ value: unknown;
+ /** Absolute file path, for source-located findings. Omit for value-only mode. */
+ file?: string | null;
+ /** Raw file source, for source-located findings. */
+ source?: string | null;
+ /** yaml@2 Document AST, for source-located findings. */
+ doc?: Document | null;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Walk a raw committed project config and return one finding per project-local
+ * leaf present in it. A registered leaf stops the descent (even an object /
+ * array leaf like `server.bind`); an unregistered container recurses; an
+ * unregistered scalar (a loose key the schema does not know) is skipped. Each
+ * finding is source-located when `file`, `source`, and `doc` are supplied.
+ */
+export function detectCommittedProjectLocalKeys(
+ input: DetectCommittedProjectLocalKeysInput,
+): IgnoredCommittedKey[] {
+ const { value, file, source, doc } = input;
+ const findings: IgnoredCommittedKey[] = [];
+
+ const walk = (node: unknown, path: string[]): void => {
+ if (path.length > 0) {
+ const meta = getLeafFieldMeta(ConfigSchema, path);
+ if (meta !== undefined) {
+ // A registered leaf: this is the scope-bearing node, so stop here.
+ if (meta.scope === 'project-local') {
+ const envVar = mechanicalEnvName(path);
+ let located: ConfigIssueSource | undefined;
+ if (doc != null && source != null && file != null) {
+ located = locateIssue({ file, source, doc, path });
+ }
+ findings.push({
+ path: [...path],
+ ...(RECOGNIZED_ENV_VARS.has(envVar) ? { envVar } : {}),
+ ...(located !== undefined ? { source: located } : {}),
+ });
+ }
+ return;
+ }
+ }
+ // Not a registered leaf: recurse into containers, ignore loose scalars.
+ if (isPlainObject(node)) {
+ for (const [key, child] of Object.entries(node)) walk(child, [...path, key]);
+ }
+ };
+
+ walk(value, []);
+ return findings;
+}
+
+/**
+ * Render a start-time warning for a project-local key found in committed
+ * config. Prefixes the `file:line:column` of the offending value when it was
+ * source-located (the IDE/CLI convention, matching `humanFormat(REMOVED_KEY)`),
+ * then names the key, states it is ignored, and points at the per-machine fix
+ * (`.ok/local/config.yml`, plus the `OK_*` env var when one exists).
+ */
+export function formatIgnoredCommittedKey(key: IgnoredCommittedKey): string {
+ const dotted = key.path.join('.');
+ const location =
+ key.source !== undefined ? `${key.source.file}:${key.source.line}:${key.source.column}: ` : '';
+ const envHint = key.envVar !== undefined ? `, or set ${key.envVar} on this host` : '';
+ return `${location}${dotted} is a per-machine (project-local) setting; the value committed in .ok/config.yml is ignored. Set it in .ok/local/config.yml (this machine only)${envHint}.`;
+}
diff --git a/packages/core/src/config/field-registry.test.ts b/packages/core/src/config/field-registry.test.ts
index ce3c1f24f..66871404f 100644
--- a/packages/core/src/config/field-registry.test.ts
+++ b/packages/core/src/config/field-registry.test.ts
@@ -267,11 +267,10 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'
'lossCapture.maxBytes',
'remote.port',
'remote.url',
- // `server.{port,bind,externalUrl}` are the committed, reviewed shape of
- // this knowledge base's server — project scope, like the `remote.*`
- // keys they supersede. Their consent/workflow siblings are
- // project-local (below).
- 'server.bind',
+ // `server.{port,externalUrl}` are the committed, reviewed shape of this
+ // knowledge base's server — project scope, like the `remote.*` keys they
+ // supersede. `server.bind` and the rest of the listener's consent/workflow
+ // siblings are project-local (below).
'server.externalUrl',
'server.port',
'server.publicUrl',
@@ -325,9 +324,12 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'
// `server.allowExternal` is exposure CONSENT — the `terminal.enabled`
// posture: never inherited via clone, sync, or share, so a committed
// `allowExternal: true` can never expose a future cloner's machine.
+ // `server.bind` is per-machine for the same clone-safety reason: a
+ // committed non-loopback bind must never break a teammate's local run.
// `server.{openBrowser,idleShutdown}` are personal workflow, like the
// sidebar toggles.
'server.allowExternal',
+ 'server.bind',
'server.idleShutdown',
'server.openBrowser',
'terminal.enabled',
diff --git a/packages/core/src/config/merge-layered.test.ts b/packages/core/src/config/merge-layered.test.ts
index 7b83ef797..a1d039a52 100644
--- a/packages/core/src/config/merge-layered.test.ts
+++ b/packages/core/src/config/merge-layered.test.ts
@@ -227,15 +227,47 @@ describe('mergeLayered — scope-aware leaf short-circuits', () => {
expect(merged.terminal?.enabled).toBeNull();
});
- test("scope: 'project' (server.bind) returns project, ignoring a project-local override attempt", () => {
+ test("scope: 'project-local' (server.bind) ignores a committed project value; the project-local layer wins", () => {
+ // server.bind is per-machine: a committed bind (one machine exposing the
+ // server) must never reach a teammate's local run — only this machine's
+ // gitignored project-local layer sets it. Same posture as allowExternal.
const user = makeConfig({});
- const project = makeConfig({ server: { bind: ['127.0.0.1'] } });
- const projectLocal = makeConfig({ server: { bind: ['0.0.0.0'] } });
+ const project = makeConfig({ server: { bind: ['0.0.0.0'] } });
+ const projectLocal = makeConfig({ server: { bind: ['192.168.1.5'] } });
+
+ const merged = mergeLayered(user, project, projectLocal);
+ expect(merged.server?.bind).toEqual(['192.168.1.5']);
+ });
+
+ test('a clone with a committed non-loopback bind but no project-local layer falls to the loopback default', () => {
+ // The exact footgun: a repo commits `server.bind: [0.0.0.0]` so one box
+ // serves remotely; every teammate who clones and runs locally must still
+ // bind loopback (and boot), never inherit the committed non-loopback value
+ // (which would trip the exposure interlock they never consented to).
+ const user = makeConfig({});
+ const project = makeConfig({ server: { bind: ['0.0.0.0'] } });
+ const projectLocal = makeConfig({});
const merged = mergeLayered(user, project, projectLocal);
expect(merged.server?.bind).toEqual(['127.0.0.1']);
});
+ test('RAW-layer path: a committed bind is skipped; a user-global bind is honored as a personal default', () => {
+ // The loader's inputs are RAW (un-parsed) partials. A committed project
+ // `bind` surfaces no `bind` from the merge (→ the final parse fills the
+ // loopback default), while a user-global bind still wins as a cross-project
+ // personal default (the project-local fallback is user, never project).
+ const committed = mergeLayered({}, { server: { bind: ['0.0.0.0'] } }, {});
+ expect((committed.server as { bind?: string[] } | undefined)?.bind).toBeUndefined();
+
+ const userDefault = mergeLayered(
+ { server: { bind: ['::1'] } },
+ { server: { bind: ['0.0.0.0'] } },
+ {},
+ );
+ expect((userDefault.server as { bind?: string[] } | undefined)?.bind).toEqual(['::1']);
+ });
+
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 —
diff --git a/packages/core/src/config/schema.test.ts b/packages/core/src/config/schema.test.ts
index 482feb9f9..76310c8ac 100644
--- a/packages/core/src/config/schema.test.ts
+++ b/packages/core/src/config/schema.test.ts
@@ -7,6 +7,7 @@ import {
isValidAttachmentFolderPath,
normalizeAttachmentFolderPath,
} from './schema.ts';
+import { getLeafFieldMeta } from './schema-leaf.ts';
describe('checkEmbeddingsBaseUrl', () => {
test('accepts https endpoints', () => {
@@ -420,6 +421,15 @@ describe('server.* (canonical listener/exposure surface)', () => {
expect(ConfigSchema.safeParse({ server: { bind: '127.0.0.1' } }).success).toBe(false);
});
+ test('bind is registered project-local so a committed value is ignored (clone-safety)', () => {
+ // Per-machine listener knob: a committed non-loopback bind must never break
+ // a teammate who clones and runs locally, so it lives in .ok/local, not the
+ // shared .ok/config.yml. mergeLayered keys off this scope to drop it.
+ const meta = getLeafFieldMeta(ConfigSchema, ['server', 'bind']);
+ expect(meta?.scope).toBe('project-local');
+ expect(meta?.defaultScope).toBe('project-local');
+ });
+
test('the deprecated publicUrl spelling still validates with the same URL shape', () => {
expect(
ConfigSchema.parse({ server: { publicUrl: 'https://kb.example.com' } }).server.publicUrl,
diff --git a/packages/core/src/config/schema.ts b/packages/core/src/config/schema.ts
index 015ab597f..56eb3372a 100644
--- a/packages/core/src/config/schema.ts
+++ b/packages/core/src/config/schema.ts
@@ -1245,13 +1245,22 @@ export const ConfigSchema = z.looseObject({
// target that drifts from the values that actually matter; "hosted" is
// just what a non-loopback bind, a public URL, and consent look like.
//
- // Scopes: `port` / `bind` / `externalUrl` are PROJECT — the committed,
- // reviewed shape of this knowledge base's server. `openBrowser` /
- // `idleShutdown` are PROJECT-LOCAL — personal workflow, like the sidebar
- // toggles. `allowExternal` is PROJECT-LOCAL consent, the same posture as
- // `terminal.enabled`: consent never travels via git, clone, or share, so a
- // committed `allowExternal: true` can never expose a future cloner's
- // machine (containers consent via environment instead).
+ // Scopes: `port` / `externalUrl` are PROJECT — the committed, reviewed shape
+ // of this knowledge base's server. `bind` is PROJECT-LOCAL, alongside
+ // `allowExternal` / `openBrowser` / `idleShutdown`: it is a per-machine
+ // listener knob, and a committed non-loopback `bind` would otherwise refuse to
+ // boot for every teammate who clones the repo and runs it locally — the
+ // exposure interlock needs per-machine `allowExternal` consent, which is never
+ // committed. Keeping `bind` project-local makes a committed value inert (the
+ // loader's scope-aware merge skips the committed layer), so one machine
+ // exposing the server can't break local clones for the rest of the team; the
+ // exposing host sets it per-machine via `OK_BIND` / `--bind` or
+ // `.ok/local/config.yml`. `allowExternal` is PROJECT-LOCAL consent, the same
+ // posture as `terminal.enabled`: consent never travels via git, clone, or
+ // share, so a committed `allowExternal: true` can never expose a future
+ // cloner's machine (containers consent via environment instead). `openBrowser`
+ // / `idleShutdown` are PROJECT-LOCAL personal workflow, like the sidebar
+ // toggles.
//
// `agentSettable: false` on every leaf, same reasoning as `remote.*`: an
// agent must never widen its own network exposure.
@@ -1282,12 +1291,12 @@ export const ConfigSchema = z.looseObject({
.array(z.string().min(1))
.min(1)
.register(fieldRegistry, {
- scope: 'project',
+ scope: 'project-local',
agentSettable: false,
reload: 'boot',
- defaultScope: 'project',
+ defaultScope: 'project-local',
description:
- 'Addresses the server binds, e.g. [127.0.0.1] or [0.0.0.0]. Default loopback-only ([127.0.0.1]): nothing off this machine can connect. A non-loopback bind additionally requires the server.allowExternal consent interlock. Lists replace, never merge. Read at server start; changing it requires a restart.',
+ 'Addresses the server binds, e.g. [127.0.0.1] or [0.0.0.0]. Default loopback-only ([127.0.0.1]): nothing off this machine can connect. A non-loopback bind additionally requires the server.allowExternal consent interlock. Per-machine (project-local): a value committed to .ok/config.yml is ignored, so one machine exposing the server can never break local clones for the rest of the team — the exposing host sets it via OK_BIND, --bind, or .ok/local/config.yml. Lists replace, never merge. Read at server start; changing it requires a restart.',
})
.default([...DEFAULT_SERVER_BIND]),
externalUrl: z
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index e68fd34c2..bf9e41315 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -166,6 +166,12 @@ export {
type OkignoreDocProvider,
type OkignoreUnsubscribe,
} from './config/bind-okignore-doc.ts';
+export {
+ type DetectCommittedProjectLocalKeysInput,
+ detectCommittedProjectLocalKeys,
+ formatIgnoredCommittedKey,
+ type IgnoredCommittedKey,
+} from './config/committed-scope-diagnostics.ts';
export {
applyConfigOverlay,
type EnvConfigLayer,