Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(ok): Wave 2 group 9 local-op prefix family native (PRD-8402) (#4036)

omar-inkeep6593e3910ce2
diff --git a/.changeset/forwarded-header-refusal-diagnostic.md b/.changeset/forwarded-header-refusal-diagnostic.md
new file mode 100644
index 000000000..b278ee9ba
--- /dev/null
+++ b/.changeset/forwarded-header-refusal-diagnostic.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+The server now logs a one-time diagnostic the first time it refuses a request carrying a forwarding header (`X-Forwarded-For`, `Forwarded`, etc.). The refusal itself is not new — a server that has not consented to external exposure has always refused proxied requests on every surface except the `/healthz` and `/readyz` probes — but the reason was easy to misread as a proxy misconfiguration. The new message names the fix: set `server.externalUrl` to the public origin in `.ok/config.yml` (or `OK_EXTERNAL_URL`) AND consent with `server.allowExternal: true` in `.ok/local/config.yml` (or `OK_ALLOW_EXTERNAL=1`) — the keys live in different files because consent is per-machine and must not travel; tolerance for forwarding headers requires the pair. `server.allowExternal` consents to exposing a server with no authentication of its own, so only set it behind an authenticating edge.
diff --git a/docs/content/remote-control/authentication.mdx b/docs/content/remote-control/authentication.mdx
index 990dba8d4..fbd1b3a65 100644
--- a/docs/content/remote-control/authentication.mdx
+++ b/docs/content/remote-control/authentication.mdx
@@ -262,7 +262,8 @@ Alternatives to the Pomerium recipe above, as pointers rather than full recipes:
Common symptoms and their fixes:
- **The editor loads but never syncs, and the browser console shows a `ws://` "Mixed Content" error.** The proxy terminates TLS but reports the request to the server as plain HTTP, so the server hands the editor an insecure `ws://` socket. Make the proxy forward `X-Forwarded-Proto: https` (Caddy: `header_up X-Forwarded-Proto https`).
-- **Every request returns `403`.** The request `Host` does not match `OK_EXTERNAL_URL`. Configure the proxy to preserve the client's `Host`. For Caddy, use `header_up Host {host}`. Set `OK_EXTERNAL_URL` to the public origin. See the full [proxy rules](/docs/remote-control/methods/docker#rules-for-anything-in-front-of-the-server).
+- **Every request returns `403` with a problem-JSON `"title"` of `Host header not allowed.`.** The request `Host` does not match `OK_EXTERNAL_URL`. Configure the proxy to preserve the client's `Host`. For Caddy, use `header_up Host {host}`. Set `OK_EXTERNAL_URL` to the public origin. See the full [proxy rules](/docs/remote-control/methods/docker#rules-for-anything-in-front-of-the-server).
+- **Every request returns `403` with a problem-JSON `"title"` of `Proxied request refused: ...`.** The proxy stamps forwarding headers (`X-Forwarded-For`, `Forwarded`, `X-Forwarded-Proto`, ...) but the server has not consented to external exposure. Set BOTH `OK_EXTERNAL_URL` to the public origin and `OK_ALLOW_EXTERNAL=1` — tolerance for forwarding headers requires the pair, and `OK_EXTERNAL_URL` alone is not enough. `OK_ALLOW_EXTERNAL` consents to exposing a server with no authentication of its own, so only set it behind an authenticating edge.
- **The browser login returns to the login page.** oauth2-proxy is rejecting the post-login redirect because the domain is not allowed. Add the public domain to `OAUTH2_PROXY_WHITELIST_DOMAINS`.
- **An agent gets an HTML login page back from `/mcp`.** The `/mcp` path is behind the browser login instead of a token. Route `/mcp` around the login proxy and gate it with a token, or if you use an MCP-OAuth edge, confirm the client supports it (see [Connect remote agents](/docs/remote-control/connecting-agents)).
- **`/mcp` hangs or times out.** A proxy is buffering the streamed response. Turn off buffering for `/mcp`. In nginx, set `proxy_buffering` to `off`. For oauth2-proxy, set `FLUSH_INTERVAL=100ms`. Caddy streams by default.
diff --git a/docs/content/remote-control/methods/docker.mdx b/docs/content/remote-control/methods/docker.mdx
index e35cd44ac..55b972225 100644
--- a/docs/content/remote-control/methods/docker.mdx
+++ b/docs/content/remote-control/methods/docker.mdx
@@ -139,7 +139,9 @@ Two practices make this predictable:
## Rules for anything in front of the server
-Three rules apply to any proxy you place between clients and the container (an auth proxy, nginx, a CDN layer):
+Four rules apply to any proxy you place between clients and the container (an auth proxy, nginx, a CDN layer):
+
+- **The server must consent before any proxy fronts it.** A request carrying a forwarding header (`X-Forwarded-For`, `Forwarded`, `X-Forwarded-Proto`, ...) is refused with `403 Proxied request refused` unless BOTH `OK_EXTERNAL_URL` and `OK_ALLOW_EXTERNAL=1` are set. Every proxy stamps at least one of these headers, so this pair is a prerequisite for the rules below.
- **Preserve the original `Host` header.** The server compares each request's `Host` with `OK_EXTERNAL_URL`. Many reverse proxies replace `Host` with the upstream address, such as `ok:8080`. The server rejects these requests with `403`. Forward the client's host instead. In Caddy, use `header_up Host {host}`. In nginx, set the `Host` header to `$host` with `proxy_set_header`. Hosting platform edges usually preserve it automatically. A proxy you add may not.
- **Never buffer `/mcp`.** It is a streaming endpoint that uses server-sent events. A proxy that buffers or compresses the response causes agent connections to time out. In nginx, set `proxy_buffering` to `off` for this path. Caddy streams by default. Hosting platform edges pass server-sent events through. Apply this rule to any proxy you add.
diff --git a/packages/core/src/config/schema.ts b/packages/core/src/config/schema.ts
index f9fc255ca..ffd6d3c6f 100644
--- a/packages/core/src/config/schema.ts
+++ b/packages/core/src/config/schema.ts
@@ -995,7 +995,7 @@ export const ConfigSchema = z.looseObject({
reload: 'boot',
defaultScope: 'project-local',
description:
- 'Exposure consent interlock. Once the unified server boot lands, a non-loopback server.bind or a server.externalUrl without allowExternal: true will be refused at boot with a one-line fix. Default off. Per-machine (project-local) — consent never travels via git, clone, or share; containers consent via the environment instead.',
+ 'Exposure consent interlock. A non-loopback server.bind without allowExternal: true is refused at boot with a one-line fix; a server.externalUrl without it boots (a committed externalUrl never arms exposure on clones — but it is project-scoped, so its host still joins the Host/Origin allowlists there), but requests carrying forwarding headers (X-Forwarded-For etc.) are refused until consent is given — proxy tolerance requires both keys. Default off. The server has no authentication of its own, so only consent behind an authenticating edge. Per-machine (project-local) — consent never travels via git, clone, or share; containers consent via the environment instead.',
})
.default(false),
openBrowser: z
diff --git a/packages/server/src/api-extension.test.ts b/packages/server/src/api-extension.test.ts
index 3ae8269a0..ed048ddae 100644
--- a/packages/server/src/api-extension.test.ts
+++ b/packages/server/src/api-extension.test.ts
@@ -6,14 +6,11 @@ import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import {
healUnservableSkillAdmission,
indexedSkillContentPath,
- resumeSyncOnAuthEvent,
type SkillAdmissionHealState,
safeSubdir,
sanitizeFilename,
} from './api-extension.test-helper.ts';
-import type { AuthEvent } from './local-ops/types.ts';
import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
-import type { SyncEngine } from './sync-engine.ts';
describe('safeSubdir', () => {
const baseDir = '/home/user/content';
@@ -621,63 +618,6 @@ describe('handleUploadAsset — same-dir sha256 dedup (FR-2)', () => {
});
});
-describe('resumeSyncOnAuthEvent (reconnect → resume wiring)', () => {
- const makeEngineStub = (impl?: () => Promise<void>) => {
- const calls: number[] = [];
- const refreshCalls: number[] = [];
- const engine = {
- notifyCredentialsChanged: () => {
- calls.push(Date.now());
- return impl ? impl() : Promise.resolve();
- },
- refreshPushPermission: () => {
- refreshCalls.push(Date.now());
- return Promise.resolve(null);
- },
- } as unknown as SyncEngine;
- return { engine, calls, refreshCalls, getSyncEngine: () => engine };
- };
-
- const completeEvent: AuthEvent = { type: 'complete', host: 'github.com', login: 'octocat' };
- const verificationEvent: AuthEvent = {
- type: 'verification',
- user_code: 'ABCD-1234',
- verification_uri: 'https://github.com/login/device',
- expires_in: 900,
- };
- const errorEvent: AuthEvent = { type: 'error', message: 'denied' };
-
- test('a complete event resumes sync AND re-probes push permission', () => {
- const stub = makeEngineStub();
- resumeSyncOnAuthEvent(completeEvent, stub.getSyncEngine);
- expect(stub.calls.length).toBe(1);
- expect(stub.refreshCalls.length).toBe(1);
- });
-
- test('non-complete events do not resume sync or re-probe', () => {
- const stub = makeEngineStub();
- resumeSyncOnAuthEvent(verificationEvent, stub.getSyncEngine);
- resumeSyncOnAuthEvent(errorEvent, stub.getSyncEngine);
- expect(stub.calls.length).toBe(0);
- expect(stub.refreshCalls.length).toBe(0);
- });
-
- test('absent getSyncEngine is a no-op (engine dormant / not yet constructed)', () => {
- expect(() => resumeSyncOnAuthEvent(completeEvent, undefined)).not.toThrow();
- });
-
- test('a null engine is a no-op', () => {
- expect(() => resumeSyncOnAuthEvent(completeEvent, () => null)).not.toThrow();
- });
-
- test('a rejected notifyCredentialsChanged is swallowed (best-effort)', async () => {
- const stub = makeEngineStub(() => Promise.reject(new Error('boom')));
- expect(() => resumeSyncOnAuthEvent(completeEvent, stub.getSyncEngine)).not.toThrow();
- expect(stub.calls.length).toBe(1);
- await Promise.resolve();
- });
-});
-
describe('indexedSkillContentPath', () => {
let contentDir: string;
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 20f05aff9..0a74ccbbe 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -1,4 +1,3 @@
-import { type SpawnOptions, spawn } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import {
createReadStream,
@@ -17,9 +16,8 @@ import {
import { readdir, readFile, realpath, stat } from 'node:fs/promises';
import type { IncomingMessage, ServerResponse } from 'node:http';
import { homedir, tmpdir } from 'node:os';
-import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
import { pipeline } from 'node:stream/promises';
-import { setTimeout as wait } from 'node:timers/promises';
import type { Document, Extension, Hocuspocus } from '@hocuspocus/server';
import {
type AdvisoryWarning,
@@ -45,8 +43,6 @@ import {
colorFromSeed,
composeWithDerivedFrontmatter,
createCodeFenceTracker,
- DEFAULT_EMBEDDINGS_BASE_URL,
- DEFAULT_EMBEDDINGS_MODEL,
DEFAULT_LINKS_VALIDATION,
DEFAULT_LINTER_CONFIG,
type DiskEditReconciledWarning,
@@ -76,22 +72,6 @@ import {
type LintPluginFailure,
type LintViolationWarning,
LOCAL_DIR,
- LocalOpAuthCancelRequestSchema,
- LocalOpAuthEmptySuccessSchema,
- type LocalOpAuthHostRequest,
- LocalOpAuthHostRequestSchema,
- LocalOpAuthPatRequestSchema,
- LocalOpAuthPatSuccessSchema,
- LocalOpAuthSetIdentityRequestSchema,
- LocalOpAuthStatusSuccessSchema,
- type LocalOpCloneRequest,
- LocalOpCloneRequestSchema,
- LocalOpEmbeddingsMutationSuccessSchema,
- LocalOpEmbeddingsSetKeyRequestSchema,
- type LocalOpEmbeddingsTestResponse,
- LocalOpEmbeddingsTestResponseSchema,
- LocalOpOkInitRequestSchema,
- LocalOpOkInitResponseSchema,
lintDocument,
MANAGED_ARTIFACT_PREFIX_SKILL,
MarkdownlintRuleWriteRequestSchema,
@@ -167,7 +147,6 @@ import {
import {
formatRenameSubject,
formatRollbackSubject,
- resolveGitDirDetailed,
resolveProjectIdentity,
} from '@inkeep/open-knowledge-core/shadow-repo-layout';
import {
@@ -226,7 +205,6 @@ import { resolveBundledSkillDir } from './build-skill-zip.ts';
import { CommentIndex } from './comments/comment-index.ts';
import { CommentService } from './comments/comment-service.ts';
import { CommentThreadStore } from './comments/thread-store.ts';
-import { getLocalDir } from './config/paths.ts';
import { CONFIG_VALIDATION_REVERT_ORIGIN } from './config-edit-origin.ts';
import { DocInConflictError, isDocInConflict, respondDocInConflict } from './conflict-errors.ts';
import {
@@ -246,13 +224,7 @@ import {
toContentDivergenceWarning,
} from './content-divergence-gate.ts';
import { recordContributor } from './contributor-tracker.ts';
-import {
- FileEmbeddingsBackend,
- probeEmbeddingEndpoint,
- type ResolvedSemanticConfig,
- resolveEmbeddingsCredential,
- type SemanticSearchService,
-} from './embeddings/index.ts';
+import type { ResolvedSemanticConfig, SemanticSearchService } from './embeddings/index.ts';
import {
FrontmatterMalformedError,
frontmatterRefusalDetail,
@@ -300,8 +272,6 @@ import {
parseFrontmatterMetadata,
} from './page-identity.ts';
import type { RecentlyRemovedDocs } from './recently-removed-docs.ts';
-import { originGitHubHost } from './share/git-context.ts';
-import { redactShareSubprocessStderr } from './share/publish.ts';
import {
BUNDLE_IDS,
BUNDLE_SCOPE,
@@ -359,10 +329,6 @@ import {
import { composeAndWriteRawBody, type PrecomputedParse, replaceRawBody } from './bridge-intake.ts';
import type { BridgeDeriveLossReporter } from './bridge-loss-detector.ts';
import { isConfigDoc, isLinkIndexExcludedDoc, isSystemDoc } from './cc1-broadcast.ts';
-import {
- LOCAL_OP_PIPE_STDIO_OPTIONS,
- withHiddenWindowsConsole,
-} from './child-process-windows-hide.ts';
import {
isReservedProjectStatePath,
listManagedDocNamesUnderFolder,
@@ -403,7 +369,6 @@ import {
upsertFolderIndexEntry as upsertFolderIndexEntryInIndex,
} from './file-watcher.ts';
import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';
-import { isProjectRoot } from './fs/find-project-root.ts';
import {
tracedCpSync,
tracedMkdirSync,
@@ -412,17 +377,12 @@ import {
tracedWriteFileSync,
} from './fs-traced.ts';
import { withParentLock } from './git-handle.ts';
-import { writeGitIdentity } from './git-identity.ts';
import { type ApiRouteTable, createApiRequestPipeline } from './http/api-pipeline.ts';
import { catchErrors } from './http/catch-errors.ts';
import { createCommentRoutes } from './http/comment-routes.ts';
import { createConfigSystemRoutes } from './http/config-system-routes.ts';
import { createDocumentRoutes } from './http/document-routes.ts';
-import {
- createStreamingErrorWriter,
- errorResponse,
- type HttpErrorStatus,
-} from './http/error-response.ts';
+import { errorResponse, type HttpErrorStatus } from './http/error-response.ts';
import {
createFileOpsRoutes,
type ManagedRenameRewrittenDoc,
@@ -436,6 +396,7 @@ import { assertSingleRouterOwnership, type NativeApiHandle } from './http/http-a
import { createLinkGraphRoutes } from './http/link-graph-routes.ts';
import { createLintRoutes } from './http/lint-routes.ts';
import { createLocalApiDispatch, type LocalApiDispatch } from './http/local-api-dispatch.ts';
+import { createLocalOpRoutes } from './http/local-op-routes.ts';
import { methodRouter } from './http/method-router.ts';
import { createMetricsRoutes } from './http/metrics-routes.ts';
import { getRequestId } from './http/request-id.ts';
@@ -468,24 +429,12 @@ import {
isHostAdmitted,
isPeerAdmitted,
} from './ingress-policy.ts';
-import { initContent } from './init-project.ts';
import type { GuardedFetch } from './link-preview/metadata.ts';
import {
checkLocalOpSecurity as checkLocalOpSecurityBase,
createConcurrencyGuard,
- expandTilde,
- isAllowedGitUrl,
isSafeLocalPath,
} from './local-op-security.ts';
-import {
- type AuthEvent,
- cachedGhBinaryPath,
- classifyCloneError,
- runCloneSubprocess,
- runDeviceFlowSubprocess,
- runGhDeviceLoginSubprocess,
- runPatSubprocess,
-} from './local-ops/index.ts';
import { localTargetInventoryFromIndexes } from './local-target-inventory.ts';
import { getLogger } from './logger.ts';
import {
@@ -548,7 +497,6 @@ import { mutateSkillsLock, readSkillsLockFile } from './skills-lock-store.ts';
import { reportSkillInstall } from './skills-sh-install-report.ts';
import type { SyncEngine } from './sync-engine.ts';
import { getMeter, withSpan, withSpanSync } from './telemetry.ts';
-import { resolveUiRedirectPort } from './ui-redirect-port.ts';
import { computeWriteAdvisoryLinks } from './write-advisory-links.ts';
let _hintEmittedCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null = null;
@@ -628,21 +576,6 @@ export function __resetRenameTelemetryForTesting(): void {
_renameAttributionCounter = null;
}
-function onAuthCredentialLanded(getSyncEngine?: () => SyncEngine | null): void {
- const engine = getSyncEngine?.();
- if (!engine) return;
- void engine.notifyCredentialsChanged().catch(() => {});
- void engine.refreshPushPermission().catch(() => {});
-}
-
-export function resumeSyncOnAuthEvent(
- event: AuthEvent,
- getSyncEngine?: () => SyncEngine | null,
-): void {
- if (event.type !== 'complete') return;
- onAuthCredentialLanded(getSyncEngine);
-}
-
export const ROLLBACK_ORIGIN = {
source: 'local' as const,
skipStoreHooks: false,
@@ -5600,1165 +5533,118 @@ export function createApiExtension(
handler: 'asset',
assetPath,
err: streamError,
- },
- '[asset] pipeline failed mid-stream',
- );
- if (!res.destroyed) {
- res.destroy(streamError instanceof Error ? streamError : undefined);
- }
- }
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'asset',
- cause: e,
- });
- }
- },
- { handler: 'asset', method: 'GET', skipBodyParse: true },
- );
-
- const TEXT_VIEW_MAX_BYTES = 1_048_576;
- const handleAssetText = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- try {
- const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
- const assetPath = url.searchParams.get('path');
- const resolution = assetService.resolveTextAsset(assetPath);
- if (!resolution.ok) {
- const [status, type, title] = ASSET_SERVE_ERRORS[resolution.reason];
- errorResponse(res, status, type, title, {
- handler: 'asset-text',
- ...(resolution.cause !== undefined ? { cause: resolution.cause } : {}),
- });
- return;
- }
- if (resolution.size > TEXT_VIEW_MAX_BYTES) {
- errorResponse(
- res,
- 413,
- 'urn:ok:error:payload-too-large',
- `File exceeds the ${TEXT_VIEW_MAX_BYTES}-byte text-viewer cap.`,
- { handler: 'asset-text' },
- );
- return;
- }
- const bytes = await readFile(resolution.canonicalPath);
- const text = bytes.toString('utf-8');
- res.writeHead(200, {
- 'Content-Type': 'text/plain; charset=utf-8',
- 'X-Content-Type-Options': 'nosniff',
- 'Content-Disposition': 'inline',
- 'Cache-Control': 'no-store',
- });
- res.end(text);
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'asset-text',
- cause: e,
- });
- }
- },
- { handler: 'asset-text', method: 'GET', skipBodyParse: true },
- );
-
- const fileOpsService = createFileOpsService({
- contentDir,
- resolveContentEntryPath,
- docNameForPath: (relPath) => docNameForFileOperationPath(contentDir, relPath),
- docNameToRelativePath,
- listManagedDocNamesUnderFolder: (absFolderPath) =>
- listManagedDocNamesUnderFolderFromDisk(absFolderPath),
- listAffectedDocNames: (index, kind, path) =>
- listAffectedDocNames(index as Map<string, FileIndexEntry>, kind, path),
- getFileIndex,
- getConflictedFiles: () =>
- new Set(
- getSyncEngine?.()
- ?.getConflicts()
- .map((c) => c.file) ?? [],
- ),
- isDocNameInLifecycleConflict: (docName) => {
- const doc = hocuspocus.documents.get(docName);
- return doc !== undefined && isDocInConflict(doc);
- },
- captureAndCloseDocuments,
- markRecentlyRemoved: recentlyRemovedDocs
- ? (docName) => recentlyRemovedDocs.setDeleted(docName)
- : undefined,
- mutateFileIndexDelete: mutateFileIndex
- ? ({ path, docName }) => mutateFileIndex({ kind: 'delete', path, docName })
- : undefined,
- removeFolderIndexEntries,
- upsertFolderIndexPathSegments,
- deleteDerivedDocumentsBestEffort,
- invalidateReferencedAssetsCache,
- signalFiles: () => signalChannel?.('files'),
- nextAvailableDuplicateDocName: (sourceDocName) =>
- nextAvailableDuplicateDocName(contentDir, sourceDocName),
- nextAvailableDuplicateFolderPath: (sourceFolderPath) =>
- nextAvailableDuplicateFolderPath(contentDir, sourceFolderPath),
- resolveDuplicateDocPath: (docName, extension) =>
- resolveDuplicateDocPath(contentDir, docName, extension),
- collectMarkdownCopies: (folderPath) => collectMarkdownCopies(contentDir, folderPath),
- collectFolderPaths: (folderPath) => collectFolderPaths(contentDir, folderPath),
- contentFilter: contentFilter ?? undefined,
- unmarkRecentlyRemoved: recentlyRemovedDocs
- ? (docName) => recentlyRemovedDocs.delete(docName)
- : undefined,
- mutateFileIndexCreate: mutateFileIndex
- ? ({ path, docName, content }) => mutateFileIndex({ kind: 'create', path, docName, content })
- : undefined,
- recordDerivedDocumentBestEffort,
- recordDerivedMutationsBestEffort,
- });
-
- const LOCAL_OP_CLONE_KEY = '/api/local-op/clone';
- const LOCAL_OP_OK_INIT_KEY = '/api/local-op/ok-init';
- const LOCAL_OP_TIMEOUT_MS = 10 * 60 * 1000;
- const LOCAL_OP_OPEN_TIMEOUT_MS = 45_000;
- const LOCAL_OP_STDERR_ONLY_OPTIONS: { stdio: ['ignore', 'ignore', 'pipe'] } = {
- stdio: ['ignore', 'ignore', 'pipe'],
- };
- const LOCAL_OP_IGNORED_STDIO_OPTIONS: Pick<SpawnOptions, 'stdio'> = {
- stdio: 'ignore',
- };
-
- const HANDLE_LOCAL_OP_CLONE = 'local-op-clone';
- const handleLocalOpClone = withValidation(LocalOpCloneRequestSchema, handleLocalOpCloneInner, {
- handler: HANDLE_LOCAL_OP_CLONE,
- method: 'POST',
- preBodyGate: (req, res) => checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_CLONE }),
- });
- async function handleLocalOpCloneInner(
- _req: IncomingMessage,
- res: ServerResponse,
- body: LocalOpCloneRequest,
- ): Promise<void> {
- const { url, dir, branch } = body;
-
- if (!isAllowedGitUrl(url)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:url-not-allowed',
- 'URL protocol is not allowed for clone.',
- { handler: HANDLE_LOCAL_OP_CLONE, cause: new Error(`url=${url}`) },
- );
- return;
- }
- if (!isSafeLocalPath(dir)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:dir-outside-home',
- 'Clone destination must be within the user home directory.',
- { handler: HANDLE_LOCAL_OP_CLONE, cause: new Error(`dir=${dir}`) },
- );
- return;
- }
-
- if (!localOpGuard.tryAcquire(LOCAL_OP_CLONE_KEY)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'A clone operation is already in progress.',
- { handler: HANDLE_LOCAL_OP_CLONE, extraHeaders: { 'Retry-After': '30' } },
- );
- return;
- }
-
- res.writeHead(200, {
- 'Content-Type': 'application/x-ndjson',
- 'Transfer-Encoding': 'chunked',
- 'X-Content-Type-Options': 'nosniff',
- 'Cache-Control': 'no-cache',
- });
-
- const writeStreamError = createStreamingErrorWriter(res, HANDLE_LOCAL_OP_CLONE);
-
- let cloneCompleteDir: string | null = null;
-
- const flow = runCloneSubprocess({
- cliArgs: localOpCliArgs,
- url,
- dir,
- branch,
- timeoutMs: LOCAL_OP_TIMEOUT_MS,
- onEvent: (event) => {
- if (event.type === 'complete') {
- cloneCompleteDir = event.dir;
- return;
- }
- if (event.type === 'error') {
- if (event.message) {
- log.warn(
- { stderr: redactShareSubprocessStderr(event.message), url, dir },
- '[local-op/clone] clone failed',
- );
- }
- const classification = classifyCloneError(event.message ?? '');
- writeStreamError(500, 'urn:ok:error:clone-failed', classification.title, {
- detail: classification.detail || undefined,
- cause: event.message
- ? new Error(redactShareSubprocessStderr(event.message))
- : undefined,
- });
- return;
- }
- if (!res.writableEnded && !res.destroyed) {
- try {
- res.write(`${JSON.stringify(event)}\n`);
- } catch {}
- }
- },
- });
-
- void (async () => {
- try {
- await flow.done;
- if (cloneCompleteDir && !res.writableEnded && !res.destroyed) {
- const result = await startServerAtDirAndGetPort(cloneCompleteDir);
- if (!res.writableEnded && !res.destroyed) {
- if ('port' in result) {
- res.write(
- `${JSON.stringify({ type: 'complete', port: result.port, dir: cloneCompleteDir })}\n`,
- );
- } else {
- writeStreamError(
- 500,
- 'urn:ok:error:server-start-failed',
- 'Cloned successfully but failed to start the project server.',
- { cause: new Error(result.error) },
- );
- }
- }
- }
- } catch (err) {
- if (!res.writableEnded && !res.destroyed) {
- writeStreamError(
- 500,
- 'urn:ok:error:internal-server-error',
- 'Unexpected error during clone post-processing.',
- { cause: err },
- );
- } else {
- log.error(
- { err, handler: HANDLE_LOCAL_OP_CLONE },
- 'clone IIFE rejected after stream ended',
- );
- }
- } finally {
- if (!res.writableEnded) res.end();
- localOpGuard.release(LOCAL_OP_CLONE_KEY);
- }
- })();
-
- res.on('close', () => {
- flow.cancel();
- });
- }
-
- const SERVER_WITHOUT_UI_ERROR =
- 'A server is already running for this directory without a web UI (started with `--only server`, or from a build without the bundled editor). Restart it with plain `ok start` from an install that includes the web UI.';
-
- async function startServerAtDirAndGetPort(
- dir: string,
- ): Promise<{ port: number } | { error: string }> {
- const absDir = resolve(expandTilde(dir));
- const lockDir = getLocalDir(absDir);
-
- const existing = resolveUiRedirectPort(lockDir);
- if (existing === 'no-ui') return { error: SERVER_WITHOUT_UI_ERROR };
- if (existing !== null) return { port: existing };
-
- const [cmd, ...baseArgs] = localOpCliArgs;
-
- const spawnAndAwaitServer = async (): Promise<{ port: number } | { error: string }> => {
- const child = spawn(
- cmd,
- [...baseArgs, 'start'],
- withHiddenWindowsConsole({
- ...LOCAL_OP_STDERR_ONLY_OPTIONS,
- cwd: absDir,
- detached: true,
- env: { ...process.env, OK_LOCK_KIND: 'interactive' },
- }),
- );
-
- const stderrChunks: Buffer[] = [];
- child.stderr?.on('data', (chunk: Buffer) => {
- stderrChunks.push(chunk);
- log.warn(
- { cwd: absDir, msg: chunk.toString('utf-8').trim() },
- '[local-op/clone] child stderr',
- );
- });
-
- let earlyExitCode: number | null = null;
- let earlyExitSignal: NodeJS.Signals | null = null;
- let spawnErrorMessage: string | null = null;
- child.on('exit', (code, signal) => {
- earlyExitCode = code ?? -1;
- earlyExitSignal = signal ?? null;
- });
- child.on('error', (err) => {
- spawnErrorMessage = err.message;
- earlyExitCode = -1;
- log.error({ cwd: absDir, err }, '[local-op/clone] failed to spawn child');
- });
-
- child.unref();
-
- const deadline = Date.now() + LOCAL_OP_OPEN_TIMEOUT_MS;
- while (Date.now() < deadline) {
- await wait(500);
- const state = resolveUiRedirectPort(lockDir);
- if (state === 'no-ui') return { error: SERVER_WITHOUT_UI_ERROR };
- if (state !== null) return { port: state };
- if (earlyExitCode !== null) {
- const stderr = Buffer.concat(stderrChunks).toString('utf-8').trim();
- const cause = spawnErrorMessage
- ? `spawn failed: ${spawnErrorMessage}`
- : earlyExitSignal
- ? `killed by ${earlyExitSignal}`
- : `code ${earlyExitCode}`;
- const winner = resolveUiRedirectPort(lockDir);
- if (winner === 'no-ui') return { error: SERVER_WITHOUT_UI_ERROR };
- if (winner !== null) return { port: winner };
- return {
- error: `\`ok start\` exited (${cause})${stderr ? ` — ${stderr}` : ''}`,
- };
- }
- }
- const stderr = Buffer.concat(stderrChunks).toString('utf-8').trim();
- return {
- error: `Server did not start within the expected time${stderr ? ` — ${stderr}` : ''}`,
- };
- };
-
- return spawnAndAwaitServer();
- }
-
- const HANDLE_LOCAL_OP_OK_INIT = 'local-op-ok-init';
- const handleLocalOpOkInit = withValidation(
- LocalOpOkInitRequestSchema,
- async (_req, res, body) => {
- const { projectPath } = body;
-
- if (!isAbsolute(projectPath)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'projectPath must be an absolute path.',
- {
- handler: HANDLE_LOCAL_OP_OK_INIT,
- cause: new Error(`projectPath=${projectPath}`),
- },
- );
- return;
- }
-
- let canonicalPath: string;
- try {
- canonicalPath = realpathSync(projectPath);
- } catch (err) {
- successResponse(
- res,
- 200,
- LocalOpOkInitResponseSchema,
- {
- ok: false,
- reason: 'not-a-git-worktree',
- message: `projectPath does not exist or is not accessible: ${(err as Error).message}`,
- },
- { handler: HANDLE_LOCAL_OP_OK_INIT },
- );
- return;
- }
-
- if (!isSafeLocalPath(canonicalPath)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:dir-outside-home',
- 'projectPath must be within the user home directory.',
- {
- handler: HANDLE_LOCAL_OP_OK_INIT,
- cause: new Error(`projectPath=${projectPath}`),
- },
- );
- return;
- }
-
- const gitDirKind = resolveGitDirDetailed(canonicalPath).kind;
- if (gitDirKind !== 'directory' && gitDirKind !== 'linked') {
- log.warn(
- { project: basename(canonicalPath), result: 'not-a-git-worktree', kind: gitDirKind },
- `[ok-init] action=init project=${basename(canonicalPath)} result=not-a-git-worktree kind=${gitDirKind}`,
- );
- successResponse(
- res,
- 200,
- LocalOpOkInitResponseSchema,
- {
- ok: false,
- reason: 'not-a-git-worktree',
- message: `projectPath is not a git working tree (.git is ${gitDirKind}).`,
- },
- { handler: HANDLE_LOCAL_OP_OK_INIT },
- );
- return;
- }
-
- if (isProjectRoot(canonicalPath)) {
- log.warn(
- { project: basename(canonicalPath), result: 'already-initialized' },
- `[ok-init] action=init project=${basename(canonicalPath)} result=already-initialized`,
- );
- successResponse(
- res,
- 200,
- LocalOpOkInitResponseSchema,
- { ok: true, projectPath: canonicalPath },
- { handler: HANDLE_LOCAL_OP_OK_INIT },
- );
- return;
- }
-
- if (!localOpGuard.tryAcquire(LOCAL_OP_OK_INIT_KEY)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'An ok-init operation is already in progress.',
- { handler: HANDLE_LOCAL_OP_OK_INIT, extraHeaders: { 'Retry-After': '2' } },
- );
- return;
- }
-
- try {
- await withParentLock(async () => {
- initContent(canonicalPath);
- });
- log.warn(
- { project: basename(canonicalPath), result: 'success' },
- `[ok-init] action=init project=${basename(canonicalPath)} result=success`,
- );
- successResponse(
- res,
- 200,
- LocalOpOkInitResponseSchema,
- { ok: true, projectPath: canonicalPath },
- { handler: HANDLE_LOCAL_OP_OK_INIT },
- );
- } catch (err) {
- const message = err instanceof Error ? err.message : String(err);
- log.warn(
- { project: basename(canonicalPath), result: 'failed', reason: message },
- `[ok-init] action=init project=${basename(canonicalPath)} result=failed reason=${message}`,
- );
- successResponse(
- res,
- 200,
- LocalOpOkInitResponseSchema,
- { ok: false, reason: 'init-failed', message },
- { handler: HANDLE_LOCAL_OP_OK_INIT },
- );
- } finally {
- localOpGuard.release(LOCAL_OP_OK_INIT_KEY);
- }
- },
- {
- handler: HANDLE_LOCAL_OP_OK_INIT,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_OK_INIT }),
- },
- );
-
- const LOCAL_OP_AUTH_LOGIN_KEY = '/api/local-op/auth/login';
- const LOCAL_OP_AUTH_STATUS_KEY = '/api/local-op/auth/status';
- const LOCAL_OP_AUTH_REPOS_KEY = '/api/local-op/auth/repos';
- const LOCAL_OP_AUTH_SIGNOUT_KEY = '/api/local-op/auth/signout';
- const LOCAL_OP_AUTH_PAT_KEY = '/api/local-op/auth/pat';
- const LOCAL_OP_AUTH_GH_LOGIN_KEY = '/api/local-op/auth/gh-login';
-
- const LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS = 30_000;
-
- const AUTH_STREAM_HEARTBEAT_MS = authStreamHeartbeatMs ?? 15_000;
-
- const AUTH_DEVICE_FLOW_TIMEOUT_MS = 16 * 60 * 1000;
-
- const defaultAuthHost = (): string => originGitHubHost(projectDir ?? contentDir);
-
- type StreamingAuthController = { done: Promise<void>; cancel(): void };
- const authLoginInFlight: { current: StreamingAuthController | null } = { current: null };
- const authGhLoginInFlight: { current: StreamingAuthController | null } = { current: null };
-
- function streamAuthFlow(cfg: {
- res: ServerResponse;
- handler: string;
- guardKey: string;
- inFlight: { current: StreamingAuthController | null };
- concurrentMessage: string;
- streamErrorMessage: string;
- makeFlow: (onEvent: (event: AuthEvent) => void) => StreamingAuthController;
- }): void {
- const { res, handler, guardKey, inFlight, concurrentMessage, streamErrorMessage, makeFlow } =
- cfg;
-
- if (!localOpGuard.tryAcquire(guardKey)) {
- const stale = inFlight.current;
- if (!stale) {
- console.error(
- JSON.stringify({
- event: 'ok-local-op:auth-flow-slot-no-controller',
- channel: 'auth',
- transport: 'http',
- handler,
- }),
- );
- errorResponse(res, 429, 'urn:ok:error:concurrent-operation', concurrentMessage, {
- handler,
- extraHeaders: { 'Retry-After': '5' },
- });
- return;
- }
- stale.cancel();
- inFlight.current = null;
- console.warn(
- JSON.stringify({
- event: 'ok-local-op:idempotent-start-replaced-stale-slot',
- channel: 'auth',
- transport: 'http',
- handler,
- }),
- );
- }
-
- res.writeHead(200, {
- 'Content-Type': 'application/x-ndjson',
- 'Transfer-Encoding': 'chunked',
- 'X-Content-Type-Options': 'nosniff',
- 'Cache-Control': 'no-cache',
- });
- const writeStreamError = createStreamingErrorWriter(res, handler);
-
- const writeLine = (line: string): void => {
- if (res.writableEnded || res.destroyed) return;
- try {
- res.write(line);
- } catch {}
- };
-
- let heartbeat: ReturnType<typeof setInterval> | null = setInterval(() => {
- writeLine(`${JSON.stringify({ type: 'ping' })}\n`);
- }, AUTH_STREAM_HEARTBEAT_MS);
- heartbeat.unref();
- const stopHeartbeat = (): void => {
- if (heartbeat === null) return;
- clearInterval(heartbeat);
- heartbeat = null;
- };
-
- const flow = makeFlow((event: AuthEvent) => {
- if (event.type === 'error') {
- writeStreamError(500, 'urn:ok:error:auth-failed', streamErrorMessage, {
- cause: event.message ? new Error(event.message) : undefined,
- });
- return;
- }
- resumeSyncOnAuthEvent(event, getSyncEngine);
- writeLine(`${JSON.stringify(event)}\n`);
- });
- inFlight.current = flow;
-
- const onClientClose = () => {
- stopHeartbeat();
- if (inFlight.current !== flow) return;
- console.warn(
- JSON.stringify({
- event: 'ok-local-op:auth-stream-detached',
- channel: 'auth',
- transport: 'http',
- handler,
- }),
- );
- };
- res.on('close', onClientClose);
-
- void flow.done.finally(() => {
- stopHeartbeat();
- res.off('close', onClientClose);
- if (!res.writableEnded && !res.destroyed) {
- try {
- res.end();
- } catch {}
- }
- if (inFlight.current === flow) {
- inFlight.current = null;
- localOpGuard.release(guardKey);
- }
- });
- }
-
- const HANDLE_LOCAL_OP_AUTH_LOGIN = 'local-op-auth-login';
- const handleLocalOpAuthLogin = withValidation(
- LocalOpAuthHostRequestSchema,
- handleLocalOpAuthLoginInner,
- {
- handler: HANDLE_LOCAL_OP_AUTH_LOGIN,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_LOGIN }),
- },
- );
- async function handleLocalOpAuthLoginInner(
- _req: IncomingMessage,
- res: ServerResponse,
- body: LocalOpAuthHostRequest,
- ): Promise<void> {
- const host = body.host ?? defaultAuthHost();
- streamAuthFlow({
- res,
- handler: HANDLE_LOCAL_OP_AUTH_LOGIN,
- guardKey: LOCAL_OP_AUTH_LOGIN_KEY,
- inFlight: authLoginInFlight,
- concurrentMessage: 'An auth login operation is already in progress.',
- streamErrorMessage: 'Auth subprocess reported an error.',
- makeFlow: (onEvent) =>
- runDeviceFlowSubprocess({
- cliArgs: localOpCliArgs,
- host,
- timeoutMs: AUTH_DEVICE_FLOW_TIMEOUT_MS,
- onEvent,
- }),
- });
- }
-
- const HANDLE_LOCAL_OP_AUTH_GH_LOGIN = 'local-op-auth-gh-login';
- const handleLocalOpAuthGhLogin = withValidation(
- LocalOpAuthHostRequestSchema,
- async (_req, res, body) => {
- const host = body.host ?? defaultAuthHost();
- const ghPath = await cachedGhBinaryPath();
- if (ghPath === null) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:auth-failed',
- 'The GitHub CLI (gh) is not installed.',
- { handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN },
- );
- return;
- }
-
- streamAuthFlow({
- res,
- handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN,
- guardKey: LOCAL_OP_AUTH_GH_LOGIN_KEY,
- inFlight: authGhLoginInFlight,
- concurrentMessage: 'A gh sign-in is already in progress.',
- streamErrorMessage: 'gh sign-in reported an error.',
- makeFlow: (onEvent) =>
- runGhDeviceLoginSubprocess({
- host,
- ghPath,
- timeoutMs: AUTH_DEVICE_FLOW_TIMEOUT_MS,
- onEvent,
- }),
- });
- },
- {
- handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN }),
- },
- );
-
- const HANDLE_LOCAL_OP_AUTH_CANCEL = 'local-op-auth-cancel';
- const handleLocalOpAuthCancel = withValidation(
- LocalOpAuthCancelRequestSchema,
- catchErrors(
- async (_req, res, body) => {
- const target =
- body.channel === 'gh-login'
- ? { inFlight: authGhLoginInFlight, guardKey: LOCAL_OP_AUTH_GH_LOGIN_KEY }
- : { inFlight: authLoginInFlight, guardKey: LOCAL_OP_AUTH_LOGIN_KEY };
- const flow = target.inFlight.current;
- if (flow) {
- flow.cancel();
- target.inFlight.current = null;
- localOpGuard.release(target.guardKey);
- }
- successResponse(
- res,
- 200,
- LocalOpAuthEmptySuccessSchema,
- {},
- { handler: HANDLE_LOCAL_OP_AUTH_CANCEL },
- );
- },
- { handler: HANDLE_LOCAL_OP_AUTH_CANCEL, title: 'Failed to cancel the sign-in.' },
- ),
- {
- handler: HANDLE_LOCAL_OP_AUTH_CANCEL,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_CANCEL }),
- },
- );
-
- const HANDLE_LOCAL_OP_AUTH_STATUS = 'local-op-auth-status';
- const handleLocalOpAuthStatus = withValidation(
- LocalOpAuthHostRequestSchema,
- async (_req, res, body) => {
- const host = body.host ?? defaultAuthHost();
-
- if (!localOpGuard.tryAcquire(LOCAL_OP_AUTH_STATUS_KEY)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'An auth status operation is already in progress.',
- { handler: HANDLE_LOCAL_OP_AUTH_STATUS, extraHeaders: { 'Retry-After': '5' } },
- );
- return;
- }
-
- try {
- const [cmd, ...baseArgs] = localOpCliArgs;
- const spawnArgs = [...baseArgs, 'auth', 'status', '--json', '--host', host];
-
- const output = await new Promise<string>((resolve, reject) => {
- const child = spawn(
- cmd,
- spawnArgs,
- withHiddenWindowsConsole({
- ...LOCAL_OP_PIPE_STDIO_OPTIONS,
- env: { ...process.env },
- }),
- );
- let settled = false;
- const killTimer = setTimeout(() => {
- if (settled) return;
- settled = true;
- try {
- child.kill('SIGKILL');
- } catch {}
- child.stdout.destroy();
- child.stderr.destroy();
- reject(
- new Error(
- `auth status subprocess timed out after ${LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS}ms`,
- ),
- );
- }, LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS);
- killTimer.unref?.();
- const chunks: Buffer[] = [];
- child.stdout.on('data', (chunk: Buffer) => chunks.push(chunk));
- child.on('close', () => {
- if (settled) return;
- settled = true;
- clearTimeout(killTimer);
- resolve(Buffer.concat(chunks).toString('utf-8'));
- });
- child.on('error', (err) => {
- if (settled) return;
- settled = true;
- clearTimeout(killTimer);
- reject(err);
- });
- });
-
- const lines = output
- .split('\n')
- .map((l) => l.trim())
- .filter(Boolean);
- let parsed: unknown = null;
- for (let i = lines.length - 1; i >= 0; i--) {
- try {
- parsed = JSON.parse(lines[i] as string);
- break;
- } catch {}
- }
- const ghAvailable = (await cachedGhBinaryPath()) !== null;
- if (parsed !== null) {
- successResponse(
- res,
- 200,
- LocalOpAuthStatusSuccessSchema,
- { ...(parsed as Record<string, unknown>), ghAvailable },
- { handler: HANDLE_LOCAL_OP_AUTH_STATUS },
- );
- } else {
- successResponse(
- res,
- 200,
- LocalOpAuthStatusSuccessSchema,
- { authenticated: false, ghAvailable },
- { handler: HANDLE_LOCAL_OP_AUTH_STATUS },
- );
- }
- } catch (err) {
- errorResponse(res, 500, 'urn:ok:error:auth-failed', 'Auth status check failed.', {
- handler: HANDLE_LOCAL_OP_AUTH_STATUS,
- cause: err,
- });
- } finally {
- localOpGuard.release(LOCAL_OP_AUTH_STATUS_KEY);
- }
- },
- {
- handler: HANDLE_LOCAL_OP_AUTH_STATUS,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_STATUS }),
- },
- );
-
- const HANDLE_LOCAL_OP_AUTH_PAT = 'local-op-auth-pat';
- const handleLocalOpAuthPat = withValidation(
- LocalOpAuthPatRequestSchema,
- async (_req, res, body) => {
- const host = body.host ?? defaultAuthHost();
-
- if (!localOpGuard.tryAcquire(LOCAL_OP_AUTH_PAT_KEY)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'An auth operation is already in progress.',
- { handler: HANDLE_LOCAL_OP_AUTH_PAT, extraHeaders: { 'Retry-After': '5' } },
- );
- return;
- }
-
- try {
- const result = await runPatSubprocess({ cliArgs: localOpCliArgs, host, token: body.token });
- if (result.ok) {
- onAuthCredentialLanded(getSyncEngine);
- successResponse(
- res,
- 200,
- LocalOpAuthPatSuccessSchema,
- { host: result.host, login: result.login },
- { handler: HANDLE_LOCAL_OP_AUTH_PAT },
- );
- } else {
- errorResponse(res, 400, 'urn:ok:error:auth-failed', result.error, {
- handler: HANDLE_LOCAL_OP_AUTH_PAT,
- });
- }
- } catch (err) {
- errorResponse(res, 500, 'urn:ok:error:auth-failed', 'Storing the token failed.', {
- handler: HANDLE_LOCAL_OP_AUTH_PAT,
- cause: err,
- });
- } finally {
- localOpGuard.release(LOCAL_OP_AUTH_PAT_KEY);
- }
- },
- {
- handler: HANDLE_LOCAL_OP_AUTH_PAT,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_PAT }),
- },
- );
-
- const HANDLE_LOCAL_OP_AUTH_REPOS = 'local-op-auth-repos';
- const handleLocalOpAuthRepos = withValidation(
- LocalOpAuthHostRequestSchema,
- handleLocalOpAuthReposInner,
- {
- handler: HANDLE_LOCAL_OP_AUTH_REPOS,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_REPOS }),
- },
- );
- async function handleLocalOpAuthReposInner(
- _req: IncomingMessage,
- res: ServerResponse,
- body: LocalOpAuthHostRequest,
- ): Promise<void> {
- const host = body.host ?? defaultAuthHost();
-
- if (!localOpGuard.tryAcquire(LOCAL_OP_AUTH_REPOS_KEY)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'An auth repos operation is already in progress.',
- { handler: HANDLE_LOCAL_OP_AUTH_REPOS, extraHeaders: { 'Retry-After': '5' } },
- );
- return;
- }
-
- res.writeHead(200, {
- 'Content-Type': 'application/x-ndjson',
- 'Transfer-Encoding': 'chunked',
- 'X-Content-Type-Options': 'nosniff',
- 'Cache-Control': 'no-cache',
- });
-
- const writeStreamError = createStreamingErrorWriter(res, HANDLE_LOCAL_OP_AUTH_REPOS);
-
- const [cmd, ...baseArgs] = localOpCliArgs;
- const spawnArgs = [...baseArgs, 'auth', 'repos', '--json', '--host', host];
-
- let settled = false;
- let stdoutBuffer = '';
- const child = spawn(
- cmd,
- spawnArgs,
- withHiddenWindowsConsole({
- ...LOCAL_OP_PIPE_STDIO_OPTIONS,
- env: { ...process.env },
- }),
- );
-
- const killTimer = setTimeout(() => {
- if (settled) return;
- settled = true;
- try {
- child.kill('SIGKILL');
- } catch {}
- child.stdout.destroy();
- child.stderr.destroy();
- if (!res.writableEnded) {
- writeStreamError(
- 500,
- 'urn:ok:error:auth-failed',
- `Auth repos subprocess timed out after ${LOCAL_OP_TIMEOUT_MS}ms.`,
- );
- }
- res.end();
- localOpGuard.release(LOCAL_OP_AUTH_REPOS_KEY);
- }, LOCAL_OP_TIMEOUT_MS);
- killTimer.unref?.();
-
- child.stdout.on('data', (chunk: Buffer) => {
- stdoutBuffer += chunk.toString('utf-8');
- const lines = stdoutBuffer.split('\n');
- stdoutBuffer = lines.pop() ?? '';
- for (const line of lines) {
- if (!line.trim()) continue;
- let evt: { type?: unknown; message?: unknown } | null = null;
- try {
- evt = JSON.parse(line) as { type?: unknown; message?: unknown };
- } catch {}
- if (evt && evt.type === 'error') {
- const detail = typeof evt.message === 'string' ? evt.message : undefined;
- writeStreamError(
- 500,
- 'urn:ok:error:auth-failed',
- 'Auth repos subprocess reported an error.',
- { detail },
- );
- continue;
- }
- if (!res.writableEnded && !res.destroyed) {
- try {
- res.write(`${line}\n`);
- } catch {}
- }
- }
- });
-
- child.stderr.on('data', (chunk: Buffer) => {
- log.debug({ msg: chunk.toString('utf-8').trim() }, '[local-op/auth/repos] stderr');
- });
-
- child.on('close', (code) => {
- clearTimeout(killTimer);
- if (!settled) {
- settled = true;
- if (code !== 0 && !res.writableEnded) {
- writeStreamError(
- 500,
- 'urn:ok:error:auth-failed',
- `Auth repos subprocess exited with code ${code}.`,
- );
- }
- res.end();
- localOpGuard.release(LOCAL_OP_AUTH_REPOS_KEY);
- }
- });
-
- child.on('error', (err) => {
- clearTimeout(killTimer);
- if (!settled) {
- settled = true;
- if (!res.writableEnded) {
- writeStreamError(
- 500,
- 'urn:ok:error:auth-failed',
- 'Failed to spawn the auth repos subprocess.',
- { cause: err },
+ },
+ '[asset] pipeline failed mid-stream',
);
- res.end();
+ if (!res.destroyed) {
+ res.destroy(streamError instanceof Error ? streamError : undefined);
+ }
}
- localOpGuard.release(LOCAL_OP_AUTH_REPOS_KEY);
- }
- });
-
- res.on('close', () => {
- if (!settled) {
- settled = true;
- clearTimeout(killTimer);
- child.kill('SIGTERM');
- localOpGuard.release(LOCAL_OP_AUTH_REPOS_KEY);
- }
- });
- }
-
- const HANDLE_LOCAL_OP_AUTH_SIGNOUT = 'local-op-auth-signout';
- const handleLocalOpAuthSignout = withValidation(
- LocalOpAuthHostRequestSchema,
- async (_req, res, body) => {
- const host = body.host ?? defaultAuthHost();
-
- if (!localOpGuard.tryAcquire(LOCAL_OP_AUTH_SIGNOUT_KEY)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'An auth signout operation is already in progress.',
- { handler: HANDLE_LOCAL_OP_AUTH_SIGNOUT, extraHeaders: { 'Retry-After': '5' } },
- );
- return;
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'asset',
+ cause: e,
+ });
}
+ },
+ { handler: 'asset', method: 'GET', skipBodyParse: true },
+ );
+ const TEXT_VIEW_MAX_BYTES = 1_048_576;
+ const handleAssetText = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
try {
- const [cmd, ...baseArgs] = localOpCliArgs;
- const spawnArgs = [...baseArgs, 'auth', 'signout', '--host', host];
-
- await new Promise<void>((resolve, reject) => {
- const child = spawn(
- cmd,
- spawnArgs,
- withHiddenWindowsConsole({
- ...LOCAL_OP_IGNORED_STDIO_OPTIONS,
- env: { ...process.env },
- }),
- );
- let settled = false;
- const killTimer = setTimeout(() => {
- if (settled) return;
- settled = true;
- try {
- child.kill('SIGKILL');
- } catch {}
- reject(
- new Error(
- `auth signout subprocess timed out after ${LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS}ms`,
- ),
- );
- }, LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS);
- killTimer.unref?.();
- child.on('close', () => {
- if (settled) return;
- settled = true;
- clearTimeout(killTimer);
- resolve();
- });
- child.on('error', (err) => {
- if (settled) return;
- settled = true;
- clearTimeout(killTimer);
- reject(err);
+ const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+ const assetPath = url.searchParams.get('path');
+ const resolution = assetService.resolveTextAsset(assetPath);
+ if (!resolution.ok) {
+ const [status, type, title] = ASSET_SERVE_ERRORS[resolution.reason];
+ errorResponse(res, status, type, title, {
+ handler: 'asset-text',
+ ...(resolution.cause !== undefined ? { cause: resolution.cause } : {}),
});
+ return;
+ }
+ if (resolution.size > TEXT_VIEW_MAX_BYTES) {
+ errorResponse(
+ res,
+ 413,
+ 'urn:ok:error:payload-too-large',
+ `File exceeds the ${TEXT_VIEW_MAX_BYTES}-byte text-viewer cap.`,
+ { handler: 'asset-text' },
+ );
+ return;
+ }
+ const bytes = await readFile(resolution.canonicalPath);
+ const text = bytes.toString('utf-8');
+ res.writeHead(200, {
+ 'Content-Type': 'text/plain; charset=utf-8',
+ 'X-Content-Type-Options': 'nosniff',
+ 'Content-Disposition': 'inline',
+ 'Cache-Control': 'no-store',
});
-
- successResponse(
- res,
- 200,
- LocalOpAuthEmptySuccessSchema,
- {},
- {
- handler: HANDLE_LOCAL_OP_AUTH_SIGNOUT,
- },
- );
- } catch (err) {
- errorResponse(res, 500, 'urn:ok:error:auth-failed', 'Auth signout failed.', {
- handler: HANDLE_LOCAL_OP_AUTH_SIGNOUT,
- cause: err,
+ res.end(text);
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'asset-text',
+ cause: e,
});
- } finally {
- localOpGuard.release(LOCAL_OP_AUTH_SIGNOUT_KEY);
}
},
- {
- handler: HANDLE_LOCAL_OP_AUTH_SIGNOUT,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_SIGNOUT }),
- },
+ { handler: 'asset-text', method: 'GET', skipBodyParse: true },
);
- const LOCAL_OP_AUTH_SET_IDENTITY_KEY = '/api/local-op/auth/set-identity';
-
- const HANDLE_LOCAL_OP_AUTH_SET_IDENTITY = 'local-op-auth-set-identity';
- const handleLocalOpAuthSetIdentity = withValidation(
- LocalOpAuthSetIdentityRequestSchema,
- async (_req, res, body) => {
- const name = body.name.trim();
- const email = body.email.trim();
-
- if (!projectDir) {
- errorResponse(res, 503, 'urn:ok:error:no-project-dir', 'No project directory configured.', {
- handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY,
- });
- return;
- }
-
- if (!localOpGuard.tryAcquire(LOCAL_OP_AUTH_SET_IDENTITY_KEY)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'A set-identity operation is already in progress.',
- { handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY, extraHeaders: { 'Retry-After': '5' } },
- );
- return;
- }
-
- try {
- writeGitIdentity(projectDir, name, email);
- void getSyncEngine?.()
- ?.refreshIdentity()
- .catch(() => {});
- successResponse(
- res,
- 200,
- LocalOpAuthEmptySuccessSchema,
- {},
- {
- handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY,
- },
- );
- } catch (err) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Set-identity failed.', {
- handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY,
- cause: err,
- });
- } finally {
- localOpGuard.release(LOCAL_OP_AUTH_SET_IDENTITY_KEY);
- }
- },
- {
- handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY }),
+ const fileOpsService = createFileOpsService({
+ contentDir,
+ resolveContentEntryPath,
+ docNameForPath: (relPath) => docNameForFileOperationPath(contentDir, relPath),
+ docNameToRelativePath,
+ listManagedDocNamesUnderFolder: (absFolderPath) =>
+ listManagedDocNamesUnderFolderFromDisk(absFolderPath),
+ listAffectedDocNames: (index, kind, path) =>
+ listAffectedDocNames(index as Map<string, FileIndexEntry>, kind, path),
+ getFileIndex,
+ getConflictedFiles: () =>
+ new Set(
+ getSyncEngine?.()
+ ?.getConflicts()
+ .map((c) => c.file) ?? [],
+ ),
+ isDocNameInLifecycleConflict: (docName) => {
+ const doc = hocuspocus.documents.get(docName);
+ return doc !== undefined && isDocInConflict(doc);
},
- );
+ captureAndCloseDocuments,
+ markRecentlyRemoved: recentlyRemovedDocs
+ ? (docName) => recentlyRemovedDocs.setDeleted(docName)
+ : undefined,
+ mutateFileIndexDelete: mutateFileIndex
+ ? ({ path, docName }) => mutateFileIndex({ kind: 'delete', path, docName })
+ : undefined,
+ removeFolderIndexEntries,
+ upsertFolderIndexPathSegments,
+ deleteDerivedDocumentsBestEffort,
+ invalidateReferencedAssetsCache,
+ signalFiles: () => signalChannel?.('files'),
+ nextAvailableDuplicateDocName: (sourceDocName) =>
+ nextAvailableDuplicateDocName(contentDir, sourceDocName),
+ nextAvailableDuplicateFolderPath: (sourceFolderPath) =>
+ nextAvailableDuplicateFolderPath(contentDir, sourceFolderPath),
+ resolveDuplicateDocPath: (docName, extension) =>
+ resolveDuplicateDocPath(contentDir, docName, extension),
+ collectMarkdownCopies: (folderPath) => collectMarkdownCopies(contentDir, folderPath),
+ collectFolderPaths: (folderPath) => collectFolderPaths(contentDir, folderPath),
+ contentFilter: contentFilter ?? undefined,
+ unmarkRecentlyRemoved: recentlyRemovedDocs
+ ? (docName) => recentlyRemovedDocs.delete(docName)
+ : undefined,
+ mutateFileIndexCreate: mutateFileIndex
+ ? ({ path, docName, content }) => mutateFileIndex({ kind: 'create', path, docName, content })
+ : undefined,
+ recordDerivedDocumentBestEffort,
+ recordDerivedMutationsBestEffort,
+ });
const handleInstallSkill = withValidation(
InstallSkillRequestSchema,
@@ -11637,170 +10523,6 @@ export function createApiExtension(
});
searchService.prewarm();
- const HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY = 'local-op-embeddings-set-key';
- const HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY = 'local-op-embeddings-clear-key';
- const LOCAL_OP_EMBEDDINGS_GUARD = '/api/local-op/embeddings';
-
- function embeddingsKeyScope(): { projectDir: string; baseUrl: string } {
- const cfg = readSemanticProviderConfig?.();
- return {
- projectDir: projectDir ?? contentDir,
- baseUrl: cfg?.baseUrl ?? DEFAULT_EMBEDDINGS_BASE_URL,
- };
- }
-
- const handleLocalOpEmbeddingsSetKey = withValidation(
- LocalOpEmbeddingsSetKeyRequestSchema,
- async (_req, res, body) => {
- if (!localOpGuard.tryAcquire(LOCAL_OP_EMBEDDINGS_GUARD)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'An embeddings key operation is already in progress.',
- { handler: HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY, extraHeaders: { 'Retry-After': '5' } },
- );
- return;
- }
- try {
- const { projectDir: pd, baseUrl } = embeddingsKeyScope();
- await new FileEmbeddingsBackend(embeddingsSecretsFile).setForProject(pd, baseUrl, body.key);
- semanticSearch?.reloadCredential();
- successResponse(
- res,
- 200,
- LocalOpEmbeddingsMutationSuccessSchema,
- { keyPresent: true },
- {
- handler: HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY,
- extraHeaders: { 'Cache-Control': 'no-store' },
- },
- );
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to store the key.', {
- handler: HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY,
- cause: e,
- });
- } finally {
- localOpGuard.release(LOCAL_OP_EMBEDDINGS_GUARD);
- }
- },
- {
- handler: HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY }),
- },
- );
-
- const handleLocalOpEmbeddingsClearKey = withValidation(
- EmptyRequestSchema,
- async (_req, res) => {
- if (!localOpGuard.tryAcquire(LOCAL_OP_EMBEDDINGS_GUARD)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'An embeddings key operation is already in progress.',
- { handler: HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY, extraHeaders: { 'Retry-After': '5' } },
- );
- return;
- }
- try {
- const { projectDir: pd, baseUrl } = embeddingsKeyScope();
- await new FileEmbeddingsBackend(embeddingsSecretsFile).clearForProject(pd, baseUrl);
- semanticSearch?.reloadCredential();
- successResponse(
- res,
- 200,
- LocalOpEmbeddingsMutationSuccessSchema,
- { keyPresent: false },
- {
- handler: HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY,
- extraHeaders: { 'Cache-Control': 'no-store' },
- },
- );
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to clear the key.', {
- handler: HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY,
- cause: e,
- });
- } finally {
- localOpGuard.release(LOCAL_OP_EMBEDDINGS_GUARD);
- }
- },
- {
- handler: HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY }),
- },
- );
-
- const HANDLE_LOCAL_OP_EMBEDDINGS_TEST = 'local-op-embeddings-test';
- const LOCAL_OP_EMBEDDINGS_TEST_GUARD = '/api/local-op/embeddings/test';
-
- const handleLocalOpEmbeddingsTest = withValidation(
- EmptyRequestSchema,
- async (_req, res) => {
- if (!localOpGuard.tryAcquire(LOCAL_OP_EMBEDDINGS_TEST_GUARD)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'A connection test is already in progress.',
- { handler: HANDLE_LOCAL_OP_EMBEDDINGS_TEST, extraHeaders: { 'Retry-After': '5' } },
- );
- return;
- }
- try {
- const config = readSemanticProviderConfig?.() ?? {
- baseUrl: DEFAULT_EMBEDDINGS_BASE_URL,
- model: DEFAULT_EMBEDDINGS_MODEL,
- dimensions: undefined,
- };
- const cred = await resolveEmbeddingsCredential(
- new FileEmbeddingsBackend(embeddingsSecretsFile),
- projectDir ?? contentDir,
- config.baseUrl,
- );
- const echo = { endpoint: config.baseUrl, model: config.model };
- const probe =
- cred.apiKey || cred.keyless
- ? await probeEmbeddingEndpoint({
- baseUrl: config.baseUrl,
- model: config.model,
- dimensions: config.dimensions,
- apiKey: cred.apiKey ?? undefined,
- })
- : ({ ok: false, reason: 'no_key', status: undefined } as const);
- const payload: LocalOpEmbeddingsTestResponse = probe.ok
- ? { ok: true, ...echo, dimensions: probe.dimensions }
- : { ok: false, ...echo, reason: probe.reason, status: probe.status };
- successResponse(res, 200, LocalOpEmbeddingsTestResponseSchema, payload, {
- handler: HANDLE_LOCAL_OP_EMBEDDINGS_TEST,
- extraHeaders: { 'Cache-Control': 'no-store' },
- });
- } catch (e) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'Failed to test the embeddings endpoint.',
- { handler: HANDLE_LOCAL_OP_EMBEDDINGS_TEST, cause: e },
- );
- } finally {
- localOpGuard.release(LOCAL_OP_EMBEDDINGS_TEST_GUARD);
- }
- },
- {
- handler: HANDLE_LOCAL_OP_EMBEDDINGS_TEST,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_EMBEDDINGS_TEST }),
- },
- );
-
let lintConfigEpoch = 0;
function signalLintConfigChanged(): void {
lintConfigEpoch += 1;
@@ -12252,19 +10974,6 @@ export function createApiExtension(
'/api/agent-burst-diff': handleAgentBurstDiff,
'/api/save-version': handleSaveVersion,
'/api/rollback': handleRollback,
- '/api/local-op/clone': handleLocalOpClone,
- '/api/local-op/ok-init': handleLocalOpOkInit,
- '/api/local-op/auth/login': handleLocalOpAuthLogin,
- '/api/local-op/auth/status': handleLocalOpAuthStatus,
- '/api/local-op/auth/pat': handleLocalOpAuthPat,
- '/api/local-op/auth/gh-login': handleLocalOpAuthGhLogin,
- '/api/local-op/auth/cancel': handleLocalOpAuthCancel,
- '/api/local-op/auth/repos': handleLocalOpAuthRepos,
- '/api/local-op/auth/signout': handleLocalOpAuthSignout,
- '/api/local-op/auth/set-identity': handleLocalOpAuthSetIdentity,
- '/api/local-op/embeddings/set-key': handleLocalOpEmbeddingsSetKey,
- '/api/local-op/embeddings/clear-key': handleLocalOpEmbeddingsClearKey,
- '/api/local-op/embeddings/test': handleLocalOpEmbeddingsTest,
'/api/install-skill': handleInstallSkill,
};
@@ -12309,7 +11018,6 @@ export function createApiExtension(
'/api/skill/revert',
'/api/skill/track-in-git',
]);
- const STATE_MUTATING_PREFIXES: ReadonlyArray<string> = ['/api/local-op/'];
const apiRouteTable: ApiRouteTable = {
resolve(url) {
@@ -12319,8 +11027,7 @@ export function createApiExtension(
}
return { template: '/api/*' };
},
- isMutating: (url) =>
- MUTATING_ROUTES.has(url) || STATE_MUTATING_PREFIXES.some((p) => url.startsWith(p)),
+ isMutating: (url) => MUTATING_ROUTES.has(url),
};
const runApiPipeline = createApiRequestPipeline({
@@ -12468,6 +11175,19 @@ export function createApiExtension(
getPrincipal,
localOpCliArgs,
});
+ const localOpRoutes = createLocalOpRoutes({
+ projectDir,
+ contentDir,
+ log,
+ checkLocalOpSecurity,
+ localOpCliArgs,
+ localOpGuard,
+ getSyncEngine,
+ authStreamHeartbeatMs,
+ embeddingsSecretsFile,
+ readSemanticProviderConfig,
+ semanticSearch,
+ });
const fileOpsRoutes = createFileOpsRoutes({
contentDir,
projectDir,
@@ -12549,6 +11269,7 @@ export function createApiExtension(
syncRoutes,
shareRoutes,
gitRoutes,
+ localOpRoutes,
fileOpsRoutes,
seedRoutes,
systemActionsRoutes,
diff --git a/packages/server/src/api-local-op-composition.test.ts b/packages/server/src/api-local-op-composition.test.ts
new file mode 100644
index 000000000..03d032cee
--- /dev/null
+++ b/packages/server/src/api-local-op-composition.test.ts
@@ -0,0 +1,234 @@
+import { existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';
+
+const HEARTBEAT_MS = 150;
+const CHILD_BACKSTOP_MS = 15_000;
+
+let tmpRoot: string;
+let homeScratch: string;
+let server: BootedServer;
+let sigtermMarker: string;
+let completedMarker: string;
+let releaseMarker: string;
+
+function releaseGatedDeviceFlowCli(): string[] {
+ return [
+ process.execPath,
+ '-e',
+ `
+ const fs = require('node:fs');
+ process.on('SIGTERM', () => {
+ try { fs.writeFileSync(${JSON.stringify(sigtermMarker)}, '1'); } catch (e) {}
+ process.exit(0);
+ });
+ console.log(JSON.stringify({type:'verification', user_code:'WDJB-MJHT', verification_uri:'https://github.com/login/device', expires_in:900}));
+ const started = Date.now();
+ const poll = setInterval(() => {
+ if (fs.existsSync(${JSON.stringify(releaseMarker)})) {
+ clearInterval(poll);
+ try { fs.writeFileSync(${JSON.stringify(completedMarker)}, '1'); } catch (e) {}
+ console.log(JSON.stringify({type:'complete', host:'github.com', login:'octocat'}));
+ process.exit(0);
+ }
+ if (Date.now() - started > ${CHILD_BACKSTOP_MS}) {
+ clearInterval(poll);
+ process.exit(1);
+ }
+ }, 100);
+ `,
+ ];
+}
+
+beforeAll(async () => {
+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-local-op-native-'));
+ homeScratch = realpathSync(mkdtempSync(join(homedir(), '.ok-local-op-native-')));
+ const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));
+ sigtermMarker = join(tmpRoot, 'sigterm');
+ completedMarker = join(tmpRoot, 'completed');
+ releaseMarker = join(tmpRoot, 'release');
+ server = await bootCompositionRig(contentDir, {
+ localOpCliArgs: releaseGatedDeviceFlowCli(),
+ authStreamHeartbeatMs: HEARTBEAT_MS,
+ });
+ await server.ready;
+}, 60_000);
+
+afterAll(async () => {
+ try {
+ writeFileSync(releaseMarker, '1');
+ } catch {}
+ try {
+ await server?.destroy();
+ } finally {
+ await Promise.allSettled([
+ rm(tmpRoot, { recursive: true, force: true }),
+ rm(homeScratch, { recursive: true, force: true }),
+ ]);
+ }
+});
+
+describe('local-op group over the composed listener — served natively', () => {
+ test('the family is registered natively (GET → 405 + Allow: POST, x-request-id echoed)', async () => {
+ for (const path of [
+ '/api/local-op/clone',
+ '/api/local-op/ok-init',
+ '/api/local-op/auth/login',
+ '/api/local-op/auth/status',
+ '/api/local-op/embeddings/test',
+ ]) {
+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`);
+ expect(res.status, path).toBe(405);
+ expect(res.headers.get('allow'), path).toBe('POST');
+ expect(res.headers.get('x-request-id'), path).not.toBeNull();
+ }
+ });
+
+ test('the family refuses a rebound Host with 403 over the composed listener', async () => {
+ for (const path of [
+ '/api/local-op/clone',
+ '/api/local-op/auth/status',
+ '/api/local-op/embeddings/set-key',
+ ]) {
+ const res = await rawRequest(server.port, path, {
+ method: 'POST',
+ headers: { Host: 'evil.example' },
+ });
+ expect(res.status, path).toBe(403);
+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:host-not-allowed');
+ }
+ });
+
+ test('an unregistered namespace member answers the explicit 404 under the native leg', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/local-op/does-not-exist`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ });
+ expect(res.status).toBe(404);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:not-found');
+ });
+
+ test('a POST reaches the real handler (ok-init gates on absolute-path discipline, then git-worktree shape)', async () => {
+ const relative = await fetch(`http://127.0.0.1:${server.port}/api/local-op/ok-init`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ projectPath: 'not/absolute' }),
+ });
+ expect(relative.status).toBe(400);
+ expect(((await relative.json()) as { type?: string }).type).toBe(
+ 'urn:ok:error:invalid-request',
+ );
+
+ const nonGit = mkdtempSync(join(homeScratch, 'non-git-'));
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/local-op/ok-init`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ projectPath: nonGit }),
+ });
+ expect(res.status).toBe(200);
+ expect((await res.json()) as Record<string, unknown>).toMatchObject({
+ ok: false,
+ reason: 'not-a-git-worktree',
+ });
+ });
+
+ test('a forwarding header trips the proxied-request refusal on the family', async () => {
+ const res = await rawRequest(server.port, '/api/local-op/some-future-op', {
+ method: 'POST',
+ headers: { 'X-Forwarded-For': '203.0.113.7' },
+ });
+ expect(res.status).toBe(403);
+ const body = parseProblem(res.body);
+ expect(body.type).toBe('urn:ok:error:host-not-allowed');
+ expect(body.detail ?? body.title).toContain('Proxied request refused');
+ });
+
+ test('auth-login streams NDJSON end-to-end: verification, heartbeat ping, disconnect-detach', async () => {
+ rmSync(sigtermMarker, { force: true });
+ rmSync(completedMarker, { force: true });
+ rmSync(releaseMarker, { force: true });
+ const controller = new AbortController();
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/local-op/auth/login`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ signal: controller.signal,
+ });
+ expect(res.status).toBe(200);
+ expect(res.headers.get('content-type')).toBe('application/x-ndjson');
+ if (!res.body) throw new Error('no response body');
+
+ const reader = res.body.getReader();
+ const decoder = new TextDecoder();
+ let buffer = '';
+ let sawVerification = false;
+ let sawPing = false;
+ while (!(sawVerification && sawPing)) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ buffer += decoder.decode(value, { stream: true });
+ const lines = buffer.split('\n');
+ buffer = lines.pop() ?? '';
+ for (const line of lines) {
+ if (!line.trim()) continue;
+ const event = JSON.parse(line) as { type?: string };
+ if (event.type === 'verification') sawVerification = true;
+ if (event.type === 'ping') sawPing = true;
+ }
+ }
+ expect(sawVerification).toBe(true);
+ expect(sawPing).toBe(true);
+
+ expect(existsSync(completedMarker), 'child still in flight at the moment of disconnect').toBe(
+ false,
+ );
+ const warns: string[] = [];
+ const originalWarn = console.warn;
+ console.warn = (...args: unknown[]): void => {
+ if (typeof args[0] === 'string') warns.push(args[0]);
+ };
+ try {
+ controller.abort();
+ const detachDeadline = Date.now() + 5_000;
+ while (
+ !warns.some((line) => line.includes('auth-stream-detached')) &&
+ Date.now() < detachDeadline
+ ) {
+ await wait(20);
+ }
+ expect(
+ warns.some((line) => line.includes('auth-stream-detached')),
+ 'server observed the disconnect as a detach before the child was released',
+ ).toBe(true);
+ } finally {
+ console.warn = originalWarn;
+ }
+ writeFileSync(releaseMarker, '1');
+ const deadline = Date.now() + 10_000;
+ while (!existsSync(completedMarker) && Date.now() < deadline) {
+ await wait(100);
+ }
+ expect(existsSync(completedMarker), 'child ran to completion after disconnect').toBe(true);
+ expect(existsSync(sigtermMarker), 'child was never SIGTERMed by the disconnect').toBe(false);
+ rmSync(sigtermMarker, { force: true });
+ rmSync(completedMarker, { force: true });
+ rmSync(releaseMarker, { force: true });
+ }, 20_000);
+
+ test('chained groups still answer on one server (multi-group dispatch)', async () => {
+ const syncStatus = await fetch(`http://127.0.0.1:${server.port}/api/sync/status`);
+ expect(syncStatus.status).toBe(200);
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/local-op/auth/cancel`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ });
+ expect(res.status).toBe(200);
+ });
+});
diff --git a/packages/server/src/collaboration-host.test.ts b/packages/server/src/collaboration-host.test.ts
index ecc87b696..ad90ba241 100644
--- a/packages/server/src/collaboration-host.test.ts
+++ b/packages/server/src/collaboration-host.test.ts
@@ -1,9 +1,12 @@
import { EventEmitter } from 'node:events';
import { createServer } from 'node:http';
-import { afterEach, describe, expect, test, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { WebSocket } from 'ws';
import { createCollaborationHost } from './collaboration-host.ts';
-import { buildIngressPolicy } from './ingress-policy.ts';
+import {
+ __resetWarnedForwardedHeaderRefusalForTests,
+ buildIngressPolicy,
+} from './ingress-policy.ts';
function createLog() {
return {
@@ -62,6 +65,10 @@ afterEach(async () => {
vi.restoreAllMocks();
});
+beforeEach(() => {
+ __resetWarnedForwardedHeaderRefusalForTests();
+});
+
describe('createCollaborationHost', () => {
test('leaves non-collaboration upgrades completely untouched', () => {
const log = createLog();
@@ -172,6 +179,10 @@ describe('createCollaborationHost', () => {
{ url: '/collab', host: 'localhost' },
'[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_EXTERNAL_URL (or server.allowExternal + server.externalUrl in config)',
);
+ expect(log.warn).toHaveBeenCalledWith(
+ { handler: 'collab-upgrade' },
+ expect.stringContaining('server.allowExternal'),
+ );
});
test('uses the tunnel-shape admission (externalUrl + consent) for bare collaboration upgrades', () => {
diff --git a/packages/server/src/collaboration-host.ts b/packages/server/src/collaboration-host.ts
index a9852059b..cbfa96f86 100644
--- a/packages/server/src/collaboration-host.ts
+++ b/packages/server/src/collaboration-host.ts
@@ -9,6 +9,7 @@ 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 {
buildIngressPolicy,
type IngressPolicy,
@@ -17,6 +18,7 @@ import {
isPeerAdmitted,
stampIngressContext,
tripsForwardedHeaderTripwire,
+ warnForwardedHeaderRefusalOnce,
} from './ingress-policy.ts';
import type { PinoLogger } from './logger.ts';
import type { MaintenanceCoordinator } from './maintenance-coordinator.ts';
@@ -252,6 +254,7 @@ export function createCollaborationHost(options: CollaborationHostOptions): Coll
{ url: req.url, host: req.headers.host },
'[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_EXTERNAL_URL (or server.allowExternal + server.externalUrl in config)',
);
+ warnForwardedHeaderRefusalOnce(log, 'collab-upgrade');
socket.destroy();
return true;
}
diff --git a/packages/server/src/http/admit-request-surface.test.ts b/packages/server/src/http/admit-request-surface.test.ts
index a15033393..945b2a705 100644
--- a/packages/server/src/http/admit-request-surface.test.ts
+++ b/packages/server/src/http/admit-request-surface.test.ts
@@ -1,9 +1,28 @@
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 { beforeEach, describe, expect, test } from 'vitest';
+import {
+ __resetWarnedForwardedHeaderRefusalForTests,
+ buildIngressPolicy,
+ warnForwardedHeaderRefusalOnce,
+} from '../ingress-policy.ts';
+import type { PinoLogger } from '../logger.ts';
import { admitRequestSurface } from './http-app.ts';
+beforeEach(() => {
+ __resetWarnedForwardedHeaderRefusalForTests();
+});
+
+function capturingLog(): { log: PinoLogger; warns: string[] } {
+ const warns: string[] = [];
+ const log = {
+ warn: (_fields: unknown, message?: string) => {
+ if (typeof message === 'string') warns.push(message);
+ },
+ } as unknown as PinoLogger;
+ return { log, warns };
+}
+
function req(
host: string | undefined,
remoteAddress = '127.0.0.1',
@@ -92,4 +111,59 @@ describe('admitRequestSurface under allowExternal consent', () => {
expect(admitRequestSurface(req('evil.example'), res, local, 'mcp-mount')).toBe(true);
expect(status()).toBeUndefined();
});
+
+ test('a Host refusal does not emit the forwarded-header diagnostic', () => {
+ const { log, warns } = capturingLog();
+ const { res } = fakeRes();
+ expect(admitRequestSurface(req('evil.example'), res, consentPolicy, 'mcp-mount', log)).toBe(
+ false,
+ );
+ expect(warns).toEqual([]);
+ });
+
+ test('a tolerated forwarded request emits no diagnostic', () => {
+ const { log, warns } = capturingLog();
+ const { res } = fakeRes();
+ expect(
+ admitRequestSurface(
+ req('laptop.tail:55222', '100.64.0.7', { 'x-forwarded-for': '203.0.113.7' }),
+ res,
+ consentPolicy,
+ 'mcp-mount',
+ log,
+ ),
+ ).toBe(true);
+ expect(warns).toEqual([]);
+ });
+
+ test('the latch is shared across callers — a WS-site warn suppresses the HTTP-site one', () => {
+ const { log, warns } = capturingLog();
+ const local = buildIngressPolicy({});
+ warnForwardedHeaderRefusalOnce(log, 'ws-upgrade');
+ expect(warns.length).toBe(1);
+ expect(
+ admitRequestSurface(
+ req('localhost', '127.0.0.1', { 'x-forwarded-for': '203.0.113.7' }),
+ fakeRes().res,
+ local,
+ 'mcp-mount',
+ log,
+ ),
+ ).toBe(false);
+ expect(warns.length).toBe(1);
+ });
+
+ test('the first forwarded-header refusal warns ONCE with the two-knob remedy; repeats stay quiet', () => {
+ const { log, warns } = capturingLog();
+ const local = buildIngressPolicy({});
+ const forwarded = () => req('localhost', '127.0.0.1', { 'x-forwarded-for': '203.0.113.7' });
+ expect(admitRequestSurface(forwarded(), fakeRes().res, local, 'mcp-mount', log)).toBe(false);
+ expect(warns.length).toBe(1);
+ expect(warns[0]).toContain('server.externalUrl');
+ expect(warns[0]).toContain('server.allowExternal');
+ expect(warns[0]).toContain('.ok/local/config.yml');
+ expect(warns[0]).toContain('ok.api.error.count');
+ expect(admitRequestSurface(forwarded(), fakeRes().res, local, 'mcp-mount', log)).toBe(false);
+ expect(warns.length).toBe(1);
+ });
});
diff --git a/packages/server/src/http/api-pipeline.test.ts b/packages/server/src/http/api-pipeline.test.ts
index afc7b719f..267583880 100644
--- a/packages/server/src/http/api-pipeline.test.ts
+++ b/packages/server/src/http/api-pipeline.test.ts
@@ -369,6 +369,41 @@ describe('createApiRouteGroup', () => {
).toThrow(/covers no registered route/);
});
+ test('a namespace-subsuming family collapses to the wildcard claim; keys outside the prefix stay mounted', () => {
+ const group = createApiRouteGroup(
+ { '/api/thing/alpha': handler, '/api/thing/nested/beta': handler, '/api/other': handler },
+ {
+ dynamic: {
+ prefix: '/api/thing/',
+ template: '/api/thing/:op',
+ dispatch: () => undefined,
+ },
+ },
+ );
+ expect([...group.paths].sort()).toEqual(['/api/other', '/api/thing/*']);
+ const member = group.table.resolve('/api/thing/alpha');
+ expect(member?.template).toBe('/api/thing/alpha');
+ expect(member?.dispatch).toBeDefined();
+ const unknown = group.table.resolve('/api/thing/some-future-op');
+ expect(unknown?.template).toBe('/api/thing/:op');
+ expect(unknown?.dispatch).toBeUndefined();
+ });
+
+ test('a bare dynamic.prefix fails at construction — its wildcard would swallow unrelated siblings', () => {
+ expect(() =>
+ createApiRouteGroup(
+ { '/api/local-op/clone': handler },
+ {
+ dynamic: {
+ prefix: '/api/local-op',
+ template: '/api/local-op/:op',
+ dispatch: () => undefined,
+ },
+ },
+ ),
+ ).toThrow(/must end in '\/'/);
+ });
+
test('a dynamic leg claims its namespace: wildcard path, bound template, 404-able empty tail', () => {
const seen: string[] = [];
const group = createApiRouteGroup(
diff --git a/packages/server/src/http/api-pipeline.ts b/packages/server/src/http/api-pipeline.ts
index 6d14fc191..e104fab95 100644
--- a/packages/server/src/http/api-pipeline.ts
+++ b/packages/server/src/http/api-pipeline.ts
@@ -63,6 +63,11 @@ export function createApiRouteGroup<R extends ApiRouteRecord>(
const mutating: ReadonlySet<string> = new Set(opts.mutating ?? []);
const mutatingPrefixes: readonly string[] = opts.mutatingPrefixes ?? [];
const routeKeys = Object.keys(routes);
+ if (dynamic !== undefined && !dynamic.prefix.endsWith('/')) {
+ throw new Error(
+ `dynamic.prefix '${dynamic.prefix}' must end in '/' — a bare prefix mounts a wildcard that also swallows unrelated siblings ('/api/local-op' matches '/api/local-op-status')`,
+ );
+ }
for (const prefix of mutatingPrefixes) {
if (!prefix.endsWith('/')) {
throw new Error(
@@ -96,7 +101,9 @@ export function createApiRouteGroup<R extends ApiRouteRecord>(
};
return {
paths:
- dynamic !== undefined ? [...Object.keys(routes), `${dynamic.prefix}*`] : Object.keys(routes),
+ dynamic !== undefined
+ ? [...routeKeys.filter((key) => !key.startsWith(dynamic.prefix)), `${dynamic.prefix}*`]
+ : routeKeys,
table,
};
}
diff --git a/packages/server/src/http/http-app.ts b/packages/server/src/http/http-app.ts
index 7f11a9d78..67780df9e 100644
--- a/packages/server/src/http/http-app.ts
+++ b/packages/server/src/http/http-app.ts
@@ -8,6 +8,7 @@ import {
isHostAdmitted,
isPeerAdmitted,
tripsForwardedHeaderTripwire,
+ warnForwardedHeaderRefusalOnce,
} from '../ingress-policy.ts';
import type { PinoLogger } from '../logger.ts';
import { errorResponse } from './error-response.ts';
@@ -32,8 +33,12 @@ export function admitRequestSurface(
res: ServerResponse,
policy: IngressPolicy,
handler: SurfaceAdmissionCaller,
+ log?: PinoLogger,
): boolean {
if (tripsForwardedHeaderTripwire(req, policy)) {
+ if (log !== undefined) {
+ warnForwardedHeaderRefusalOnce(log, handler);
+ }
errorResponse(
res,
403,
@@ -171,7 +176,7 @@ export function createHttpApp(opts: CreateHttpAppOptions): HttpAppHandle {
opts.legacyDispatch(req, res);
return RESPONSE_ALREADY_SENT;
}
- if (!admitRequestSurface(req, res, ingressPolicy, 'native-mcp-surface')) {
+ if (!admitRequestSurface(req, res, ingressPolicy, 'native-mcp-surface', opts.log)) {
return RESPONSE_ALREADY_SENT;
}
mcpDispatch(req, res);
@@ -185,7 +190,7 @@ export function createHttpApp(opts: CreateHttpAppOptions): HttpAppHandle {
app.all(path, async (c) => {
const req = c.env.incoming;
const res = c.env.outgoing;
- if (!admitRequestSurface(req, res, ingressPolicy, 'native-api-surface')) {
+ if (!admitRequestSurface(req, res, ingressPolicy, 'native-api-surface', opts.log)) {
return RESPONSE_ALREADY_SENT;
}
try {
diff --git a/packages/server/src/http/local-op-routes.test.ts b/packages/server/src/http/local-op-routes.test.ts
new file mode 100644
index 000000000..74ae823d7
--- /dev/null
+++ b/packages/server/src/http/local-op-routes.test.ts
@@ -0,0 +1,129 @@
+import { describe, expect, test } from 'vitest';
+import { createConcurrencyGuard } from '../local-op-security.ts';
+import type { AuthEvent } from '../local-ops/types.ts';
+import { loggerFactory } from '../logger.ts';
+import type { SyncEngine } from '../sync-engine.ts';
+import { createLocalOpRoutes, resumeSyncOnAuthEvent } from './local-op-routes.ts';
+
+const LOCAL_OP_PATHS = [
+ '/api/local-op/clone',
+ '/api/local-op/ok-init',
+ '/api/local-op/auth/login',
+ '/api/local-op/auth/status',
+ '/api/local-op/auth/pat',
+ '/api/local-op/auth/gh-login',
+ '/api/local-op/auth/cancel',
+ '/api/local-op/auth/repos',
+ '/api/local-op/auth/signout',
+ '/api/local-op/auth/set-identity',
+ '/api/local-op/embeddings/set-key',
+ '/api/local-op/embeddings/clear-key',
+ '/api/local-op/embeddings/test',
+];
+
+function buildGroup() {
+ return createLocalOpRoutes({
+ projectDir: undefined,
+ contentDir: '/tmp/ok-local-op-routes-test',
+ log: loggerFactory.getLogger('test'),
+ checkLocalOpSecurity: () => true,
+ localOpCliArgs: ['open-knowledge'],
+ localOpGuard: createConcurrencyGuard(),
+ getSyncEngine: undefined,
+ authStreamHeartbeatMs: undefined,
+ embeddingsSecretsFile: undefined,
+ readSemanticProviderConfig: undefined,
+ semanticSearch: undefined,
+ });
+}
+
+describe('createLocalOpRoutes table', () => {
+ test('claims the namespace with a single wildcard and resolves all thirteen members', () => {
+ const group = buildGroup();
+ expect([...group.paths]).toEqual(['/api/local-op/*']);
+ for (const path of LOCAL_OP_PATHS) {
+ const resolution = group.table.resolve(path);
+ expect(resolution?.template, path).toBe(path);
+ expect(resolution?.dispatch, path).toBeDefined();
+ }
+ });
+
+ test('every registered member is mutating (prefix-family membership)', () => {
+ const { table } = buildGroup();
+ for (const path of LOCAL_OP_PATHS) {
+ expect(table.isMutating(path), path).toBe(true);
+ }
+ });
+
+ test('an unregistered member is owned by the namespace leg, 404-bound, and mutating by default', () => {
+ const { table } = buildGroup();
+ const resolution = table.resolve('/api/local-op/some-future-op');
+ expect(resolution).not.toBeNull();
+ expect(resolution?.template).toBe('/api/local-op/:op');
+ expect(resolution?.dispatch).toBeUndefined();
+ expect(table.isMutating('/api/local-op/some-future-op')).toBe(true);
+ });
+
+ test('a bare-prefix sibling outside the family is not owned and not mutating', () => {
+ const { table } = buildGroup();
+ expect(table.resolve('/api/local-op-status')).toBeNull();
+ expect(table.isMutating('/api/local-op-status')).toBe(false);
+ });
+});
+
+describe('resumeSyncOnAuthEvent (reconnect → resume wiring)', () => {
+ const makeEngineStub = (impl?: () => Promise<void>) => {
+ const calls: number[] = [];
+ const refreshCalls: number[] = [];
+ const engine = {
+ notifyCredentialsChanged: () => {
+ calls.push(Date.now());
+ return impl ? impl() : Promise.resolve();
+ },
+ refreshPushPermission: () => {
+ refreshCalls.push(Date.now());
+ return Promise.resolve(null);
+ },
+ } as unknown as SyncEngine;
+ return { engine, calls, refreshCalls, getSyncEngine: () => engine };
+ };
+
+ const completeEvent: AuthEvent = { type: 'complete', host: 'github.com', login: 'octocat' };
+ const verificationEvent: AuthEvent = {
+ type: 'verification',
+ user_code: 'ABCD-1234',
+ verification_uri: 'https://github.com/login/device',
+ expires_in: 900,
+ };
+ const errorEvent: AuthEvent = { type: 'error', message: 'denied' };
+
+ test('a complete event resumes sync AND re-probes push permission', () => {
+ const stub = makeEngineStub();
+ resumeSyncOnAuthEvent(completeEvent, stub.getSyncEngine);
+ expect(stub.calls.length).toBe(1);
+ expect(stub.refreshCalls.length).toBe(1);
+ });
+
+ test('non-complete events do not resume sync or re-probe', () => {
+ const stub = makeEngineStub();
+ resumeSyncOnAuthEvent(verificationEvent, stub.getSyncEngine);
+ resumeSyncOnAuthEvent(errorEvent, stub.getSyncEngine);
+ expect(stub.calls.length).toBe(0);
+ expect(stub.refreshCalls.length).toBe(0);
+ });
+
+ test('absent getSyncEngine is a no-op (engine dormant / not yet constructed)', () => {
+ expect(() => resumeSyncOnAuthEvent(completeEvent, undefined)).not.toThrow();
+ });
+
+ test('a null engine is a no-op', () => {
+ expect(() => resumeSyncOnAuthEvent(completeEvent, () => null)).not.toThrow();
+ });
+
+ test('a rejected notifyCredentialsChanged is swallowed (best-effort)', async () => {
+ const stub = makeEngineStub(() => Promise.reject(new Error('boom')));
+ expect(() => resumeSyncOnAuthEvent(completeEvent, stub.getSyncEngine)).not.toThrow();
+ expect(stub.calls.length).toBe(1);
+ await Promise.resolve();
+ });
+});
diff --git a/packages/server/src/http/local-op-routes.ts b/packages/server/src/http/local-op-routes.ts
new file mode 100644
index 000000000..92cf58521
--- /dev/null
+++ b/packages/server/src/http/local-op-routes.ts
@@ -0,0 +1,1352 @@
+import { type SpawnOptions, spawn } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { basename, isAbsolute, resolve } from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+import {
+ DEFAULT_EMBEDDINGS_BASE_URL,
+ DEFAULT_EMBEDDINGS_MODEL,
+ EmptyRequestSchema,
+ LocalOpAuthCancelRequestSchema,
+ LocalOpAuthEmptySuccessSchema,
+ type LocalOpAuthHostRequest,
+ LocalOpAuthHostRequestSchema,
+ LocalOpAuthPatRequestSchema,
+ LocalOpAuthPatSuccessSchema,
+ LocalOpAuthSetIdentityRequestSchema,
+ LocalOpAuthStatusSuccessSchema,
+ type LocalOpCloneRequest,
+ LocalOpCloneRequestSchema,
+ LocalOpEmbeddingsMutationSuccessSchema,
+ LocalOpEmbeddingsSetKeyRequestSchema,
+ type LocalOpEmbeddingsTestResponse,
+ LocalOpEmbeddingsTestResponseSchema,
+ LocalOpOkInitRequestSchema,
+ LocalOpOkInitResponseSchema,
+} from '@inkeep/open-knowledge-core';
+import { resolveGitDirDetailed } from '@inkeep/open-knowledge-core/shadow-repo-layout';
+import {
+ LOCAL_OP_PIPE_STDIO_OPTIONS,
+ withHiddenWindowsConsole,
+} from '../child-process-windows-hide.ts';
+import { getLocalDir } from '../config/paths.ts';
+import {
+ FileEmbeddingsBackend,
+ probeEmbeddingEndpoint,
+ type ResolvedSemanticConfig,
+ resolveEmbeddingsCredential,
+ type SemanticSearchService,
+} from '../embeddings/index.ts';
+import { isProjectRoot } from '../fs/find-project-root.ts';
+import { withParentLock } from '../git-handle.ts';
+import { writeGitIdentity } from '../git-identity.ts';
+import { initContent } from '../init-project.ts';
+import {
+ type ConcurrencyGuard,
+ expandTilde,
+ isAllowedGitUrl,
+ isSafeLocalPath,
+} from '../local-op-security.ts';
+import {
+ type AuthEvent,
+ cachedGhBinaryPath,
+ classifyCloneError,
+ runCloneSubprocess,
+ runDeviceFlowSubprocess,
+ runGhDeviceLoginSubprocess,
+ runPatSubprocess,
+} from '../local-ops/index.ts';
+import type { PinoLogger } from '../logger.ts';
+import { originGitHubHost } from '../share/git-context.ts';
+import { redactShareSubprocessStderr } from '../share/publish.ts';
+import type { SyncEngine } from '../sync-engine.ts';
+import { resolveUiRedirectPort } from '../ui-redirect-port.ts';
+import { type ApiRouteGroup, type ApiRouteRecord, createApiRouteGroup } from './api-pipeline.ts';
+import { catchErrors } from './catch-errors.ts';
+import { createStreamingErrorWriter, errorResponse } from './error-response.ts';
+import { withValidation } from './request-validation.ts';
+import { successResponse } from './success-response.ts';
+
+function onAuthCredentialLanded(getSyncEngine?: () => SyncEngine | null): void {
+ const engine = getSyncEngine?.();
+ if (!engine) return;
+ void engine.notifyCredentialsChanged().catch(() => {});
+ void engine.refreshPushPermission().catch(() => {});
+}
+
+export function resumeSyncOnAuthEvent(
+ event: AuthEvent,
+ getSyncEngine?: () => SyncEngine | null,
+): void {
+ if (event.type !== 'complete') return;
+ onAuthCredentialLanded(getSyncEngine);
+}
+
+export interface LocalOpRouteDeps {
+ projectDir: string | undefined;
+ contentDir: string;
+ log: PinoLogger;
+ checkLocalOpSecurity: (
+ req: IncomingMessage,
+ res: ServerResponse,
+ opts: { handler: string },
+ ) => boolean;
+ localOpCliArgs: string[];
+ localOpGuard: ConcurrencyGuard;
+ getSyncEngine: (() => SyncEngine | null) | undefined;
+ authStreamHeartbeatMs: number | undefined;
+ embeddingsSecretsFile: string | undefined;
+ readSemanticProviderConfig: (() => ResolvedSemanticConfig) | undefined;
+ semanticSearch: SemanticSearchService | undefined;
+}
+
+export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
+ const {
+ projectDir,
+ contentDir,
+ log,
+ checkLocalOpSecurity,
+ localOpCliArgs,
+ localOpGuard,
+ getSyncEngine,
+ authStreamHeartbeatMs,
+ embeddingsSecretsFile,
+ readSemanticProviderConfig,
+ semanticSearch,
+ } = deps;
+
+ const LOCAL_OP_CLONE_KEY = '/api/local-op/clone';
+ const LOCAL_OP_OK_INIT_KEY = '/api/local-op/ok-init';
+ const LOCAL_OP_TIMEOUT_MS = 10 * 60 * 1000;
+ const LOCAL_OP_OPEN_TIMEOUT_MS = 45_000;
+ const LOCAL_OP_STDERR_ONLY_OPTIONS: { stdio: ['ignore', 'ignore', 'pipe'] } = {
+ stdio: ['ignore', 'ignore', 'pipe'],
+ };
+ const LOCAL_OP_IGNORED_STDIO_OPTIONS: Pick<SpawnOptions, 'stdio'> = {
+ stdio: 'ignore',
+ };
+
+ const HANDLE_LOCAL_OP_CLONE = 'local-op-clone';
+ const handleLocalOpClone = withValidation(LocalOpCloneRequestSchema, handleLocalOpCloneInner, {
+ handler: HANDLE_LOCAL_OP_CLONE,
+ method: 'POST',
+ preBodyGate: (req, res) => checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_CLONE }),
+ });
+ async function handleLocalOpCloneInner(
+ _req: IncomingMessage,
+ res: ServerResponse,
+ body: LocalOpCloneRequest,
+ ): Promise<void> {
+ const { url, dir, branch } = body;
+
+ if (!isAllowedGitUrl(url)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:url-not-allowed',
+ 'URL protocol is not allowed for clone.',
+ { handler: HANDLE_LOCAL_OP_CLONE, cause: new Error(`url=${url}`) },
+ );
+ return;
+ }
+ if (!isSafeLocalPath(dir)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:dir-outside-home',
+ 'Clone destination must be within the user home directory.',
+ { handler: HANDLE_LOCAL_OP_CLONE, cause: new Error(`dir=${dir}`) },
+ );
+ return;
+ }
+
+ if (!localOpGuard.tryAcquire(LOCAL_OP_CLONE_KEY)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'A clone operation is already in progress.',
+ { handler: HANDLE_LOCAL_OP_CLONE, extraHeaders: { 'Retry-After': '30' } },
+ );
+ return;
+ }
+
+ res.writeHead(200, {
+ 'Content-Type': 'application/x-ndjson',
+ 'Transfer-Encoding': 'chunked',
+ 'X-Content-Type-Options': 'nosniff',
+ 'Cache-Control': 'no-cache',
+ });
+
+ const writeStreamError = createStreamingErrorWriter(res, HANDLE_LOCAL_OP_CLONE);
+
+ let cloneCompleteDir: string | null = null;
+
+ const flow = runCloneSubprocess({
+ cliArgs: localOpCliArgs,
+ url,
+ dir,
+ branch,
+ timeoutMs: LOCAL_OP_TIMEOUT_MS,
+ onEvent: (event) => {
+ if (event.type === 'complete') {
+ cloneCompleteDir = event.dir;
+ return;
+ }
+ if (event.type === 'error') {
+ if (event.message) {
+ log.warn(
+ { stderr: redactShareSubprocessStderr(event.message), url, dir },
+ '[local-op/clone] clone failed',
+ );
+ }
+ const classification = classifyCloneError(event.message ?? '');
+ writeStreamError(500, 'urn:ok:error:clone-failed', classification.title, {
+ detail: classification.detail || undefined,
+ cause: event.message
+ ? new Error(redactShareSubprocessStderr(event.message))
+ : undefined,
+ });
+ return;
+ }
+ if (!res.writableEnded && !res.destroyed) {
+ try {
+ res.write(`${JSON.stringify(event)}\n`);
+ } catch {}
+ }
+ },
+ });
+
+ void (async () => {
+ try {
+ await flow.done;
+ if (cloneCompleteDir && !res.writableEnded && !res.destroyed) {
+ const result = await startServerAtDirAndGetPort(cloneCompleteDir);
+ if (!res.writableEnded && !res.destroyed) {
+ if ('port' in result) {
+ res.write(
+ `${JSON.stringify({ type: 'complete', port: result.port, dir: cloneCompleteDir })}\n`,
+ );
+ } else {
+ writeStreamError(
+ 500,
+ 'urn:ok:error:server-start-failed',
+ 'Cloned successfully but failed to start the project server.',
+ { cause: new Error(result.error) },
+ );
+ }
+ }
+ }
+ } catch (err) {
+ if (!res.writableEnded && !res.destroyed) {
+ writeStreamError(
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'Unexpected error during clone post-processing.',
+ { cause: err },
+ );
+ } else {
+ log.error(
+ { err, handler: HANDLE_LOCAL_OP_CLONE },
+ 'clone IIFE rejected after stream ended',
+ );
+ }
+ } finally {
+ if (!res.writableEnded) res.end();
+ localOpGuard.release(LOCAL_OP_CLONE_KEY);
+ }
+ })();
+
+ res.on('close', () => {
+ flow.cancel();
+ });
+ }
+
+ const SERVER_WITHOUT_UI_ERROR =
+ 'A server is already running for this directory without a web UI (started with `--only server`, or from a build without the bundled editor). Restart it with plain `ok start` from an install that includes the web UI.';
+
+ async function startServerAtDirAndGetPort(
+ dir: string,
+ ): Promise<{ port: number } | { error: string }> {
+ const absDir = resolve(expandTilde(dir));
+ const lockDir = getLocalDir(absDir);
+
+ const existing = resolveUiRedirectPort(lockDir);
+ if (existing === 'no-ui') return { error: SERVER_WITHOUT_UI_ERROR };
+ if (existing !== null) return { port: existing };
+
+ const [cmd, ...baseArgs] = localOpCliArgs;
+
+ const spawnAndAwaitServer = async (): Promise<{ port: number } | { error: string }> => {
+ const child = spawn(
+ cmd,
+ [...baseArgs, 'start'],
+ withHiddenWindowsConsole({
+ ...LOCAL_OP_STDERR_ONLY_OPTIONS,
+ cwd: absDir,
+ detached: true,
+ env: { ...process.env, OK_LOCK_KIND: 'interactive' },
+ }),
+ );
+
+ const stderrChunks: Buffer[] = [];
+ child.stderr?.on('data', (chunk: Buffer) => {
+ stderrChunks.push(chunk);
+ log.warn(
+ { cwd: absDir, msg: chunk.toString('utf-8').trim() },
+ '[local-op/clone] child stderr',
+ );
+ });
+
+ let earlyExitCode: number | null = null;
+ let earlyExitSignal: NodeJS.Signals | null = null;
+ let spawnErrorMessage: string | null = null;
+ child.on('exit', (code, signal) => {
+ earlyExitCode = code ?? -1;
+ earlyExitSignal = signal ?? null;
+ });
+ child.on('error', (err) => {
+ spawnErrorMessage = err.message;
+ earlyExitCode = -1;
+ log.error({ cwd: absDir, err }, '[local-op/clone] failed to spawn child');
+ });
+
+ child.unref();
+
+ const deadline = Date.now() + LOCAL_OP_OPEN_TIMEOUT_MS;
+ while (Date.now() < deadline) {
+ await wait(500);
+ const state = resolveUiRedirectPort(lockDir);
+ if (state === 'no-ui') return { error: SERVER_WITHOUT_UI_ERROR };
+ if (state !== null) return { port: state };
+ if (earlyExitCode !== null) {
+ const stderr = Buffer.concat(stderrChunks).toString('utf-8').trim();
+ const cause = spawnErrorMessage
+ ? `spawn failed: ${spawnErrorMessage}`
+ : earlyExitSignal
+ ? `killed by ${earlyExitSignal}`
+ : `code ${earlyExitCode}`;
+ const winner = resolveUiRedirectPort(lockDir);
+ if (winner === 'no-ui') return { error: SERVER_WITHOUT_UI_ERROR };
+ if (winner !== null) return { port: winner };
+ return {
+ error: `\`ok start\` exited (${cause})${stderr ? ` — ${stderr}` : ''}`,
+ };
+ }
+ }
+ const stderr = Buffer.concat(stderrChunks).toString('utf-8').trim();
+ return {
+ error: `Server did not start within the expected time${stderr ? ` — ${stderr}` : ''}`,
+ };
+ };
+
+ return spawnAndAwaitServer();
+ }
+
+ const HANDLE_LOCAL_OP_OK_INIT = 'local-op-ok-init';
+ const handleLocalOpOkInit = withValidation(
+ LocalOpOkInitRequestSchema,
+ async (_req, res, body) => {
+ const { projectPath } = body;
+
+ if (!isAbsolute(projectPath)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'projectPath must be an absolute path.',
+ {
+ handler: HANDLE_LOCAL_OP_OK_INIT,
+ cause: new Error(`projectPath=${projectPath}`),
+ },
+ );
+ return;
+ }
+
+ let canonicalPath: string;
+ try {
+ canonicalPath = realpathSync(projectPath);
+ } catch (err) {
+ successResponse(
+ res,
+ 200,
+ LocalOpOkInitResponseSchema,
+ {
+ ok: false,
+ reason: 'not-a-git-worktree',
+ message: `projectPath does not exist or is not accessible: ${(err as Error).message}`,
+ },
+ { handler: HANDLE_LOCAL_OP_OK_INIT },
+ );
+ return;
+ }
+
+ if (!isSafeLocalPath(canonicalPath)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:dir-outside-home',
+ 'projectPath must be within the user home directory.',
+ {
+ handler: HANDLE_LOCAL_OP_OK_INIT,
+ cause: new Error(`projectPath=${projectPath}`),
+ },
+ );
+ return;
+ }
+
+ const gitDirKind = resolveGitDirDetailed(canonicalPath).kind;
+ if (gitDirKind !== 'directory' && gitDirKind !== 'linked') {
+ log.warn(
+ { project: basename(canonicalPath), result: 'not-a-git-worktree', kind: gitDirKind },
+ `[ok-init] action=init project=${basename(canonicalPath)} result=not-a-git-worktree kind=${gitDirKind}`,
+ );
+ successResponse(
+ res,
+ 200,
+ LocalOpOkInitResponseSchema,
+ {
+ ok: false,
+ reason: 'not-a-git-worktree',
+ message: `projectPath is not a git working tree (.git is ${gitDirKind}).`,
+ },
+ { handler: HANDLE_LOCAL_OP_OK_INIT },
+ );
+ return;
+ }
+
+ if (isProjectRoot(canonicalPath)) {
+ log.warn(
+ { project: basename(canonicalPath), result: 'already-initialized' },
+ `[ok-init] action=init project=${basename(canonicalPath)} result=already-initialized`,
+ );
+ successResponse(
+ res,
+ 200,
+ LocalOpOkInitResponseSchema,
+ { ok: true, projectPath: canonicalPath },
+ { handler: HANDLE_LOCAL_OP_OK_INIT },
+ );
+ return;
+ }
+
+ if (!localOpGuard.tryAcquire(LOCAL_OP_OK_INIT_KEY)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'An ok-init operation is already in progress.',
+ { handler: HANDLE_LOCAL_OP_OK_INIT, extraHeaders: { 'Retry-After': '2' } },
+ );
+ return;
+ }
+
+ try {
+ await withParentLock(async () => {
+ initContent(canonicalPath);
+ });
+ log.warn(
+ { project: basename(canonicalPath), result: 'success' },
+ `[ok-init] action=init project=${basename(canonicalPath)} result=success`,
+ );
+ successResponse(
+ res,
+ 200,
+ LocalOpOkInitResponseSchema,
+ { ok: true, projectPath: canonicalPath },
+ { handler: HANDLE_LOCAL_OP_OK_INIT },
+ );
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ log.warn(
+ { project: basename(canonicalPath), result: 'failed', reason: message },
+ `[ok-init] action=init project=${basename(canonicalPath)} result=failed reason=${message}`,
+ );
+ successResponse(
+ res,
+ 200,
+ LocalOpOkInitResponseSchema,
+ { ok: false, reason: 'init-failed', message },
+ { handler: HANDLE_LOCAL_OP_OK_INIT },
+ );
+ } finally {
+ localOpGuard.release(LOCAL_OP_OK_INIT_KEY);
+ }
+ },
+ {
+ handler: HANDLE_LOCAL_OP_OK_INIT,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_OK_INIT }),
+ },
+ );
+
+ const LOCAL_OP_AUTH_LOGIN_KEY = '/api/local-op/auth/login';
+ const LOCAL_OP_AUTH_STATUS_KEY = '/api/local-op/auth/status';
+ const LOCAL_OP_AUTH_REPOS_KEY = '/api/local-op/auth/repos';
+ const LOCAL_OP_AUTH_SIGNOUT_KEY = '/api/local-op/auth/signout';
+ const LOCAL_OP_AUTH_PAT_KEY = '/api/local-op/auth/pat';
+ const LOCAL_OP_AUTH_GH_LOGIN_KEY = '/api/local-op/auth/gh-login';
+
+ const LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS = 30_000;
+
+ const AUTH_STREAM_HEARTBEAT_MS = authStreamHeartbeatMs ?? 15_000;
+
+ const AUTH_DEVICE_FLOW_TIMEOUT_MS = 16 * 60 * 1000;
+
+ const defaultAuthHost = (): string => originGitHubHost(projectDir ?? contentDir);
+
+ type StreamingAuthController = { done: Promise<void>; cancel(): void };
+ const authLoginInFlight: { current: StreamingAuthController | null } = { current: null };
+ const authGhLoginInFlight: { current: StreamingAuthController | null } = { current: null };
+
+ function streamAuthFlow(cfg: {
+ res: ServerResponse;
+ handler: string;
+ guardKey: string;
+ inFlight: { current: StreamingAuthController | null };
+ concurrentMessage: string;
+ streamErrorMessage: string;
+ makeFlow: (onEvent: (event: AuthEvent) => void) => StreamingAuthController;
+ }): void {
+ const { res, handler, guardKey, inFlight, concurrentMessage, streamErrorMessage, makeFlow } =
+ cfg;
+
+ if (!localOpGuard.tryAcquire(guardKey)) {
+ const stale = inFlight.current;
+ if (!stale) {
+ console.error(
+ JSON.stringify({
+ event: 'ok-local-op:auth-flow-slot-no-controller',
+ channel: 'auth',
+ transport: 'http',
+ handler,
+ }),
+ );
+ errorResponse(res, 429, 'urn:ok:error:concurrent-operation', concurrentMessage, {
+ handler,
+ extraHeaders: { 'Retry-After': '5' },
+ });
+ return;
+ }
+ stale.cancel();
+ inFlight.current = null;
+ console.warn(
+ JSON.stringify({
+ event: 'ok-local-op:idempotent-start-replaced-stale-slot',
+ channel: 'auth',
+ transport: 'http',
+ handler,
+ }),
+ );
+ }
+
+ res.writeHead(200, {
+ 'Content-Type': 'application/x-ndjson',
+ 'Transfer-Encoding': 'chunked',
+ 'X-Content-Type-Options': 'nosniff',
+ 'Cache-Control': 'no-cache',
+ });
+ const writeStreamError = createStreamingErrorWriter(res, handler);
+
+ const writeLine = (line: string): void => {
+ if (res.writableEnded || res.destroyed) return;
+ try {
+ res.write(line);
+ } catch {}
+ };
+
+ let heartbeat: ReturnType<typeof setInterval> | null = setInterval(() => {
+ writeLine(`${JSON.stringify({ type: 'ping' })}\n`);
+ }, AUTH_STREAM_HEARTBEAT_MS);
+ heartbeat.unref();
+ const stopHeartbeat = (): void => {
+ if (heartbeat === null) return;
+ clearInterval(heartbeat);
+ heartbeat = null;
+ };
+
+ const flow = makeFlow((event: AuthEvent) => {
+ if (event.type === 'error') {
+ writeStreamError(500, 'urn:ok:error:auth-failed', streamErrorMessage, {
+ cause: event.message ? new Error(event.message) : undefined,
+ });
+ return;
+ }
+ resumeSyncOnAuthEvent(event, getSyncEngine);
+ writeLine(`${JSON.stringify(event)}\n`);
+ });
+ inFlight.current = flow;
+
+ const onClientClose = () => {
+ stopHeartbeat();
+ if (inFlight.current !== flow) return;
+ console.warn(
+ JSON.stringify({
+ event: 'ok-local-op:auth-stream-detached',
+ channel: 'auth',
+ transport: 'http',
+ handler,
+ }),
+ );
+ };
+ res.on('close', onClientClose);
+
+ void flow.done.finally(() => {
+ stopHeartbeat();
+ res.off('close', onClientClose);
+ if (!res.writableEnded && !res.destroyed) {
+ try {
+ res.end();
+ } catch {}
+ }
+ if (inFlight.current === flow) {
+ inFlight.current = null;
+ localOpGuard.release(guardKey);
+ }
+ });
+ }
+
+ const HANDLE_LOCAL_OP_AUTH_LOGIN = 'local-op-auth-login';
+ const handleLocalOpAuthLogin = withValidation(
+ LocalOpAuthHostRequestSchema,
+ handleLocalOpAuthLoginInner,
+ {
+ handler: HANDLE_LOCAL_OP_AUTH_LOGIN,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_LOGIN }),
+ },
+ );
+ async function handleLocalOpAuthLoginInner(
+ _req: IncomingMessage,
+ res: ServerResponse,
+ body: LocalOpAuthHostRequest,
+ ): Promise<void> {
+ const host = body.host ?? defaultAuthHost();
+ streamAuthFlow({
+ res,
+ handler: HANDLE_LOCAL_OP_AUTH_LOGIN,
+ guardKey: LOCAL_OP_AUTH_LOGIN_KEY,
+ inFlight: authLoginInFlight,
+ concurrentMessage: 'An auth login operation is already in progress.',
+ streamErrorMessage: 'Auth subprocess reported an error.',
+ makeFlow: (onEvent) =>
+ runDeviceFlowSubprocess({
+ cliArgs: localOpCliArgs,
+ host,
+ timeoutMs: AUTH_DEVICE_FLOW_TIMEOUT_MS,
+ onEvent,
+ }),
+ });
+ }
+
+ const HANDLE_LOCAL_OP_AUTH_GH_LOGIN = 'local-op-auth-gh-login';
+ const handleLocalOpAuthGhLogin = withValidation(
+ LocalOpAuthHostRequestSchema,
+ async (_req, res, body) => {
+ const host = body.host ?? defaultAuthHost();
+ const ghPath = await cachedGhBinaryPath();
+ if (ghPath === null) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:auth-failed',
+ 'The GitHub CLI (gh) is not installed.',
+ { handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN },
+ );
+ return;
+ }
+
+ streamAuthFlow({
+ res,
+ handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN,
+ guardKey: LOCAL_OP_AUTH_GH_LOGIN_KEY,
+ inFlight: authGhLoginInFlight,
+ concurrentMessage: 'A gh sign-in is already in progress.',
+ streamErrorMessage: 'gh sign-in reported an error.',
+ makeFlow: (onEvent) =>
+ runGhDeviceLoginSubprocess({
+ host,
+ ghPath,
+ timeoutMs: AUTH_DEVICE_FLOW_TIMEOUT_MS,
+ onEvent,
+ }),
+ });
+ },
+ {
+ handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN }),
+ },
+ );
+
+ const HANDLE_LOCAL_OP_AUTH_CANCEL = 'local-op-auth-cancel';
+ const handleLocalOpAuthCancel = withValidation(
+ LocalOpAuthCancelRequestSchema,
+ catchErrors(
+ async (_req, res, body) => {
+ const target =
+ body.channel === 'gh-login'
+ ? { inFlight: authGhLoginInFlight, guardKey: LOCAL_OP_AUTH_GH_LOGIN_KEY }
+ : { inFlight: authLoginInFlight, guardKey: LOCAL_OP_AUTH_LOGIN_KEY };
+ const flow = target.inFlight.current;
+ if (flow) {
+ flow.cancel();
+ target.inFlight.current = null;
+ localOpGuard.release(target.guardKey);
+ }
+ successResponse(
+ res,
+ 200,
+ LocalOpAuthEmptySuccessSchema,
+ {},
+ { handler: HANDLE_LOCAL_OP_AUTH_CANCEL },
+ );
+ },
+ { handler: HANDLE_LOCAL_OP_AUTH_CANCEL, title: 'Failed to cancel the sign-in.' },
+ ),
+ {
+ handler: HANDLE_LOCAL_OP_AUTH_CANCEL,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_CANCEL }),
+ },
+ );
+
+ const HANDLE_LOCAL_OP_AUTH_STATUS = 'local-op-auth-status';
+ const handleLocalOpAuthStatus = withValidation(
+ LocalOpAuthHostRequestSchema,
+ async (_req, res, body) => {
+ const host = body.host ?? defaultAuthHost();
+
+ if (!localOpGuard.tryAcquire(LOCAL_OP_AUTH_STATUS_KEY)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'An auth status operation is already in progress.',
+ { handler: HANDLE_LOCAL_OP_AUTH_STATUS, extraHeaders: { 'Retry-After': '5' } },
+ );
+ return;
+ }
+
+ try {
+ const [cmd, ...baseArgs] = localOpCliArgs;
+ const spawnArgs = [...baseArgs, 'auth', 'status', '--json', '--host', host];
+
+ const output = await new Promise<string>((resolve, reject) => {
+ const child = spawn(
+ cmd,
+ spawnArgs,
+ withHiddenWindowsConsole({
+ ...LOCAL_OP_PIPE_STDIO_OPTIONS,
+ env: { ...process.env },
+ }),
+ );
+ let settled = false;
+ const killTimer = setTimeout(() => {
+ if (settled) return;
+ settled = true;
+ try {
+ child.kill('SIGKILL');
+ } catch {}
+ child.stdout.destroy();
+ child.stderr.destroy();
+ reject(
+ new Error(
+ `auth status subprocess timed out after ${LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS}ms`,
+ ),
+ );
+ }, LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS);
+ killTimer.unref?.();
+ const chunks: Buffer[] = [];
+ child.stdout.on('data', (chunk: Buffer) => chunks.push(chunk));
+ child.on('close', () => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(killTimer);
+ resolve(Buffer.concat(chunks).toString('utf-8'));
+ });
+ child.on('error', (err) => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(killTimer);
+ reject(err);
+ });
+ });
+
+ const lines = output
+ .split('\n')
+ .map((l) => l.trim())
+ .filter(Boolean);
+ let parsed: unknown = null;
+ for (let i = lines.length - 1; i >= 0; i--) {
+ try {
+ parsed = JSON.parse(lines[i] as string);
+ break;
+ } catch {}
+ }
+ const ghAvailable = (await cachedGhBinaryPath()) !== null;
+ if (parsed !== null) {
+ successResponse(
+ res,
+ 200,
+ LocalOpAuthStatusSuccessSchema,
+ { ...(parsed as Record<string, unknown>), ghAvailable },
+ { handler: HANDLE_LOCAL_OP_AUTH_STATUS },
+ );
+ } else {
+ successResponse(
+ res,
+ 200,
+ LocalOpAuthStatusSuccessSchema,
+ { authenticated: false, ghAvailable },
+ { handler: HANDLE_LOCAL_OP_AUTH_STATUS },
+ );
+ }
+ } catch (err) {
+ errorResponse(res, 500, 'urn:ok:error:auth-failed', 'Auth status check failed.', {
+ handler: HANDLE_LOCAL_OP_AUTH_STATUS,
+ cause: err,
+ });
+ } finally {
+ localOpGuard.release(LOCAL_OP_AUTH_STATUS_KEY);
+ }
+ },
+ {
+ handler: HANDLE_LOCAL_OP_AUTH_STATUS,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_STATUS }),
+ },
+ );
+
+ const HANDLE_LOCAL_OP_AUTH_PAT = 'local-op-auth-pat';
+ const handleLocalOpAuthPat = withValidation(
+ LocalOpAuthPatRequestSchema,
+ async (_req, res, body) => {
+ const host = body.host ?? defaultAuthHost();
+
+ if (!localOpGuard.tryAcquire(LOCAL_OP_AUTH_PAT_KEY)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'An auth operation is already in progress.',
+ { handler: HANDLE_LOCAL_OP_AUTH_PAT, extraHeaders: { 'Retry-After': '5' } },
+ );
+ return;
+ }
+
+ try {
+ const result = await runPatSubprocess({ cliArgs: localOpCliArgs, host, token: body.token });
+ if (result.ok) {
+ onAuthCredentialLanded(getSyncEngine);
+ successResponse(
+ res,
+ 200,
+ LocalOpAuthPatSuccessSchema,
+ { host: result.host, login: result.login },
+ { handler: HANDLE_LOCAL_OP_AUTH_PAT },
+ );
+ } else {
+ errorResponse(res, 400, 'urn:ok:error:auth-failed', result.error, {
+ handler: HANDLE_LOCAL_OP_AUTH_PAT,
+ });
+ }
+ } catch (err) {
+ errorResponse(res, 500, 'urn:ok:error:auth-failed', 'Storing the token failed.', {
+ handler: HANDLE_LOCAL_OP_AUTH_PAT,
+ cause: err,
+ });
+ } finally {
+ localOpGuard.release(LOCAL_OP_AUTH_PAT_KEY);
+ }
+ },
+ {
+ handler: HANDLE_LOCAL_OP_AUTH_PAT,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_PAT }),
+ },
+ );
+
+ const HANDLE_LOCAL_OP_AUTH_REPOS = 'local-op-auth-repos';
+ const handleLocalOpAuthRepos = withValidation(
+ LocalOpAuthHostRequestSchema,
+ handleLocalOpAuthReposInner,
+ {
+ handler: HANDLE_LOCAL_OP_AUTH_REPOS,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_REPOS }),
+ },
+ );
+ async function handleLocalOpAuthReposInner(
+ _req: IncomingMessage,
+ res: ServerResponse,
+ body: LocalOpAuthHostRequest,
+ ): Promise<void> {
+ const host = body.host ?? defaultAuthHost();
+
+ if (!localOpGuard.tryAcquire(LOCAL_OP_AUTH_REPOS_KEY)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'An auth repos operation is already in progress.',
+ { handler: HANDLE_LOCAL_OP_AUTH_REPOS, extraHeaders: { 'Retry-After': '5' } },
+ );
+ return;
+ }
+
+ res.writeHead(200, {
+ 'Content-Type': 'application/x-ndjson',
+ 'Transfer-Encoding': 'chunked',
+ 'X-Content-Type-Options': 'nosniff',
+ 'Cache-Control': 'no-cache',
+ });
+
+ const writeStreamError = createStreamingErrorWriter(res, HANDLE_LOCAL_OP_AUTH_REPOS);
+
+ const [cmd, ...baseArgs] = localOpCliArgs;
+ const spawnArgs = [...baseArgs, 'auth', 'repos', '--json', '--host', host];
+
+ let settled = false;
+ let stdoutBuffer = '';
+ const child = spawn(
+ cmd,
+ spawnArgs,
+ withHiddenWindowsConsole({
+ ...LOCAL_OP_PIPE_STDIO_OPTIONS,
+ env: { ...process.env },
+ }),
+ );
+
+ const killTimer = setTimeout(() => {
+ if (settled) return;
+ settled = true;
+ try {
+ child.kill('SIGKILL');
+ } catch {}
+ child.stdout.destroy();
+ child.stderr.destroy();
+ if (!res.writableEnded) {
+ writeStreamError(
+ 500,
+ 'urn:ok:error:auth-failed',
+ `Auth repos subprocess timed out after ${LOCAL_OP_TIMEOUT_MS}ms.`,
+ );
+ }
+ res.end();
+ localOpGuard.release(LOCAL_OP_AUTH_REPOS_KEY);
+ }, LOCAL_OP_TIMEOUT_MS);
+ killTimer.unref?.();
+
+ child.stdout.on('data', (chunk: Buffer) => {
+ stdoutBuffer += chunk.toString('utf-8');
+ const lines = stdoutBuffer.split('\n');
+ stdoutBuffer = lines.pop() ?? '';
+ for (const line of lines) {
+ if (!line.trim()) continue;
+ let evt: { type?: unknown; message?: unknown } | null = null;
+ try {
+ evt = JSON.parse(line) as { type?: unknown; message?: unknown };
+ } catch {}
+ if (evt && evt.type === 'error') {
+ const detail = typeof evt.message === 'string' ? evt.message : undefined;
+ writeStreamError(
+ 500,
+ 'urn:ok:error:auth-failed',
+ 'Auth repos subprocess reported an error.',
+ { detail },
+ );
+ continue;
+ }
+ if (!res.writableEnded && !res.destroyed) {
+ try {
+ res.write(`${line}\n`);
+ } catch {}
+ }
+ }
+ });
+
+ child.stderr.on('data', (chunk: Buffer) => {
+ log.debug({ msg: chunk.toString('utf-8').trim() }, '[local-op/auth/repos] stderr');
+ });
+
+ child.on('close', (code) => {
+ clearTimeout(killTimer);
+ if (!settled) {
+ settled = true;
+ if (code !== 0 && !res.writableEnded) {
+ writeStreamError(
+ 500,
+ 'urn:ok:error:auth-failed',
+ `Auth repos subprocess exited with code ${code}.`,
+ );
+ }
+ res.end();
+ localOpGuard.release(LOCAL_OP_AUTH_REPOS_KEY);
+ }
+ });
+
+ child.on('error', (err) => {
+ clearTimeout(killTimer);
+ if (!settled) {
+ settled = true;
+ if (!res.writableEnded) {
+ writeStreamError(
+ 500,
+ 'urn:ok:error:auth-failed',
+ 'Failed to spawn the auth repos subprocess.',
+ { cause: err },
+ );
+ res.end();
+ }
+ localOpGuard.release(LOCAL_OP_AUTH_REPOS_KEY);
+ }
+ });
+
+ res.on('close', () => {
+ if (!settled) {
+ settled = true;
+ clearTimeout(killTimer);
+ child.kill('SIGTERM');
+ localOpGuard.release(LOCAL_OP_AUTH_REPOS_KEY);
+ }
+ });
+ }
+
+ const HANDLE_LOCAL_OP_AUTH_SIGNOUT = 'local-op-auth-signout';
+ const handleLocalOpAuthSignout = withValidation(
+ LocalOpAuthHostRequestSchema,
+ async (_req, res, body) => {
+ const host = body.host ?? defaultAuthHost();
+
+ if (!localOpGuard.tryAcquire(LOCAL_OP_AUTH_SIGNOUT_KEY)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'An auth signout operation is already in progress.',
+ { handler: HANDLE_LOCAL_OP_AUTH_SIGNOUT, extraHeaders: { 'Retry-After': '5' } },
+ );
+ return;
+ }
+
+ try {
+ const [cmd, ...baseArgs] = localOpCliArgs;
+ const spawnArgs = [...baseArgs, 'auth', 'signout', '--host', host];
+
+ await new Promise<void>((resolve, reject) => {
+ const child = spawn(
+ cmd,
+ spawnArgs,
+ withHiddenWindowsConsole({
+ ...LOCAL_OP_IGNORED_STDIO_OPTIONS,
+ env: { ...process.env },
+ }),
+ );
+ let settled = false;
+ const killTimer = setTimeout(() => {
+ if (settled) return;
+ settled = true;
+ try {
+ child.kill('SIGKILL');
+ } catch {}
+ reject(
+ new Error(
+ `auth signout subprocess timed out after ${LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS}ms`,
+ ),
+ );
+ }, LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS);
+ killTimer.unref?.();
+ child.on('close', () => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(killTimer);
+ resolve();
+ });
+ child.on('error', (err) => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(killTimer);
+ reject(err);
+ });
+ });
+
+ successResponse(
+ res,
+ 200,
+ LocalOpAuthEmptySuccessSchema,
+ {},
+ {
+ handler: HANDLE_LOCAL_OP_AUTH_SIGNOUT,
+ },
+ );
+ } catch (err) {
+ errorResponse(res, 500, 'urn:ok:error:auth-failed', 'Auth signout failed.', {
+ handler: HANDLE_LOCAL_OP_AUTH_SIGNOUT,
+ cause: err,
+ });
+ } finally {
+ localOpGuard.release(LOCAL_OP_AUTH_SIGNOUT_KEY);
+ }
+ },
+ {
+ handler: HANDLE_LOCAL_OP_AUTH_SIGNOUT,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_SIGNOUT }),
+ },
+ );
+
+ const LOCAL_OP_AUTH_SET_IDENTITY_KEY = '/api/local-op/auth/set-identity';
+
+ const HANDLE_LOCAL_OP_AUTH_SET_IDENTITY = 'local-op-auth-set-identity';
+ const handleLocalOpAuthSetIdentity = withValidation(
+ LocalOpAuthSetIdentityRequestSchema,
+ async (_req, res, body) => {
+ const name = body.name.trim();
+ const email = body.email.trim();
+
+ if (!projectDir) {
+ errorResponse(res, 503, 'urn:ok:error:no-project-dir', 'No project directory configured.', {
+ handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY,
+ });
+ return;
+ }
+
+ if (!localOpGuard.tryAcquire(LOCAL_OP_AUTH_SET_IDENTITY_KEY)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'A set-identity operation is already in progress.',
+ { handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY, extraHeaders: { 'Retry-After': '5' } },
+ );
+ return;
+ }
+
+ try {
+ writeGitIdentity(projectDir, name, email);
+ void getSyncEngine?.()
+ ?.refreshIdentity()
+ .catch(() => {});
+ successResponse(
+ res,
+ 200,
+ LocalOpAuthEmptySuccessSchema,
+ {},
+ {
+ handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY,
+ },
+ );
+ } catch (err) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Set-identity failed.', {
+ handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY,
+ cause: err,
+ });
+ } finally {
+ localOpGuard.release(LOCAL_OP_AUTH_SET_IDENTITY_KEY);
+ }
+ },
+ {
+ handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_AUTH_SET_IDENTITY }),
+ },
+ );
+ const HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY = 'local-op-embeddings-set-key';
+ const HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY = 'local-op-embeddings-clear-key';
+ const LOCAL_OP_EMBEDDINGS_GUARD = '/api/local-op/embeddings';
+
+ function embeddingsKeyScope(): { projectDir: string; baseUrl: string } {
+ const cfg = readSemanticProviderConfig?.();
+ return {
+ projectDir: projectDir ?? contentDir,
+ baseUrl: cfg?.baseUrl ?? DEFAULT_EMBEDDINGS_BASE_URL,
+ };
+ }
+
+ const handleLocalOpEmbeddingsSetKey = withValidation(
+ LocalOpEmbeddingsSetKeyRequestSchema,
+ async (_req, res, body) => {
+ if (!localOpGuard.tryAcquire(LOCAL_OP_EMBEDDINGS_GUARD)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'An embeddings key operation is already in progress.',
+ { handler: HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY, extraHeaders: { 'Retry-After': '5' } },
+ );
+ return;
+ }
+ try {
+ const { projectDir: pd, baseUrl } = embeddingsKeyScope();
+ await new FileEmbeddingsBackend(embeddingsSecretsFile).setForProject(pd, baseUrl, body.key);
+ semanticSearch?.reloadCredential();
+ successResponse(
+ res,
+ 200,
+ LocalOpEmbeddingsMutationSuccessSchema,
+ { keyPresent: true },
+ {
+ handler: HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY,
+ extraHeaders: { 'Cache-Control': 'no-store' },
+ },
+ );
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to store the key.', {
+ handler: HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY,
+ cause: e,
+ });
+ } finally {
+ localOpGuard.release(LOCAL_OP_EMBEDDINGS_GUARD);
+ }
+ },
+ {
+ handler: HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_EMBEDDINGS_SET_KEY }),
+ },
+ );
+
+ const handleLocalOpEmbeddingsClearKey = withValidation(
+ EmptyRequestSchema,
+ async (_req, res) => {
+ if (!localOpGuard.tryAcquire(LOCAL_OP_EMBEDDINGS_GUARD)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'An embeddings key operation is already in progress.',
+ { handler: HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY, extraHeaders: { 'Retry-After': '5' } },
+ );
+ return;
+ }
+ try {
+ const { projectDir: pd, baseUrl } = embeddingsKeyScope();
+ await new FileEmbeddingsBackend(embeddingsSecretsFile).clearForProject(pd, baseUrl);
+ semanticSearch?.reloadCredential();
+ successResponse(
+ res,
+ 200,
+ LocalOpEmbeddingsMutationSuccessSchema,
+ { keyPresent: false },
+ {
+ handler: HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY,
+ extraHeaders: { 'Cache-Control': 'no-store' },
+ },
+ );
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to clear the key.', {
+ handler: HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY,
+ cause: e,
+ });
+ } finally {
+ localOpGuard.release(LOCAL_OP_EMBEDDINGS_GUARD);
+ }
+ },
+ {
+ handler: HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_EMBEDDINGS_CLEAR_KEY }),
+ },
+ );
+
+ const HANDLE_LOCAL_OP_EMBEDDINGS_TEST = 'local-op-embeddings-test';
+ const LOCAL_OP_EMBEDDINGS_TEST_GUARD = '/api/local-op/embeddings/test';
+
+ const handleLocalOpEmbeddingsTest = withValidation(
+ EmptyRequestSchema,
+ async (_req, res) => {
+ if (!localOpGuard.tryAcquire(LOCAL_OP_EMBEDDINGS_TEST_GUARD)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'A connection test is already in progress.',
+ { handler: HANDLE_LOCAL_OP_EMBEDDINGS_TEST, extraHeaders: { 'Retry-After': '5' } },
+ );
+ return;
+ }
+ try {
+ const config = readSemanticProviderConfig?.() ?? {
+ baseUrl: DEFAULT_EMBEDDINGS_BASE_URL,
+ model: DEFAULT_EMBEDDINGS_MODEL,
+ dimensions: undefined,
+ };
+ const cred = await resolveEmbeddingsCredential(
+ new FileEmbeddingsBackend(embeddingsSecretsFile),
+ projectDir ?? contentDir,
+ config.baseUrl,
+ );
+ const echo = { endpoint: config.baseUrl, model: config.model };
+ const probe =
+ cred.apiKey || cred.keyless
+ ? await probeEmbeddingEndpoint({
+ baseUrl: config.baseUrl,
+ model: config.model,
+ dimensions: config.dimensions,
+ apiKey: cred.apiKey ?? undefined,
+ })
+ : ({ ok: false, reason: 'no_key', status: undefined } as const);
+ const payload: LocalOpEmbeddingsTestResponse = probe.ok
+ ? { ok: true, ...echo, dimensions: probe.dimensions }
+ : { ok: false, ...echo, reason: probe.reason, status: probe.status };
+ successResponse(res, 200, LocalOpEmbeddingsTestResponseSchema, payload, {
+ handler: HANDLE_LOCAL_OP_EMBEDDINGS_TEST,
+ extraHeaders: { 'Cache-Control': 'no-store' },
+ });
+ } catch (e) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'Failed to test the embeddings endpoint.',
+ { handler: HANDLE_LOCAL_OP_EMBEDDINGS_TEST, cause: e },
+ );
+ } finally {
+ localOpGuard.release(LOCAL_OP_EMBEDDINGS_TEST_GUARD);
+ }
+ },
+ {
+ handler: HANDLE_LOCAL_OP_EMBEDDINGS_TEST,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: HANDLE_LOCAL_OP_EMBEDDINGS_TEST }),
+ },
+ );
+
+ const routes = {
+ '/api/local-op/clone': handleLocalOpClone,
+ '/api/local-op/ok-init': handleLocalOpOkInit,
+ '/api/local-op/auth/login': handleLocalOpAuthLogin,
+ '/api/local-op/auth/status': handleLocalOpAuthStatus,
+ '/api/local-op/auth/pat': handleLocalOpAuthPat,
+ '/api/local-op/auth/gh-login': handleLocalOpAuthGhLogin,
+ '/api/local-op/auth/cancel': handleLocalOpAuthCancel,
+ '/api/local-op/auth/repos': handleLocalOpAuthRepos,
+ '/api/local-op/auth/signout': handleLocalOpAuthSignout,
+ '/api/local-op/auth/set-identity': handleLocalOpAuthSetIdentity,
+ '/api/local-op/embeddings/set-key': handleLocalOpEmbeddingsSetKey,
+ '/api/local-op/embeddings/clear-key': handleLocalOpEmbeddingsClearKey,
+ '/api/local-op/embeddings/test': handleLocalOpEmbeddingsTest,
+ } satisfies ApiRouteRecord;
+
+ return createApiRouteGroup(routes, {
+ mutatingPrefixes: ['/api/local-op/'],
+ dynamic: {
+ prefix: '/api/local-op/',
+ template: '/api/local-op/:op',
+ dispatch: () => undefined,
+ },
+ });
+}
diff --git a/packages/server/src/ingress-policy.ts b/packages/server/src/ingress-policy.ts
index ef960a6b0..ef35c96ac 100644
--- a/packages/server/src/ingress-policy.ts
+++ b/packages/server/src/ingress-policy.ts
@@ -1,6 +1,7 @@
import type { IncomingMessage } from 'node:http';
import type { ServerRuntimeConfig } from '@inkeep/open-knowledge-core';
import { isAllowedApiOrigin } from './api-origin.ts';
+import type { PinoLogger } from './logger.ts';
import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';
export function normalizeHostHeader(host: string): string {
@@ -137,6 +138,31 @@ export function tripsForwardedHeaderTripwire(
return !policy.tolerateForwardedHeaders && hasForwardingHeaders(req);
}
+export type ForwardedRefusalCaller =
+ | 'mcp-mount'
+ | 'native-api-surface'
+ | 'native-mcp-surface'
+ | 'collab-upgrade'
+ | 'ws-upgrade';
+
+let warnedForwardedHeaderRefusal = false;
+
+export function __resetWarnedForwardedHeaderRefusalForTests(): void {
+ warnedForwardedHeaderRefusal = false;
+}
+
+export function warnForwardedHeaderRefusalOnce(
+ log: PinoLogger,
+ handler: ForwardedRefusalCaller,
+): void {
+ if (warnedForwardedHeaderRefusal) return;
+ warnedForwardedHeaderRefusal = true;
+ log.warn(
+ { handler },
+ '[ingress] refused a request carrying a forwarding header (X-Forwarded-For etc.) — without external-exposure consent, every surface except the /healthz + /readyz probes refuses proxied requests (APIs 403, /collab upgrades dropped). To front this server with a proxy, set server.externalUrl to the public origin in .ok/config.yml (or OK_EXTERNAL_URL) AND consent with server.allowExternal: true in .ok/local/config.yml (or OK_ALLOW_EXTERNAL=1) — the keys live in different files because consent is per-machine and never travels. allowExternal consents to exposure on a server with NO authentication — restrict access at the edge. Removing server.externalUrl does not lift this refusal (it fires on the header, not the URL) and would un-admit that Host/Origin everywhere else. Warned once per process; every refusal is still logged at warn level (HTTP refusals additionally as api.error, counted in ok.api.error.count).',
+ );
+}
+
export interface IngressRequestContext {
requestId: string | undefined;
peerClass: 'loopback' | 'external' | 'unknown';
diff --git a/packages/server/src/mcp-mount.test.ts b/packages/server/src/mcp-mount.test.ts
index c9f9766cb..3a4f88027 100644
--- a/packages/server/src/mcp-mount.test.ts
+++ b/packages/server/src/mcp-mount.test.ts
@@ -10,10 +10,13 @@ import {
INLINE_RENDERABLE_EXTENSIONS,
} from '@inkeep/open-knowledge-core';
import sirv from 'sirv';
-import { afterEach, describe, expect, test, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { WebSocket } from 'ws';
import { createAssetServeMiddleware } from './asset-serve-middleware.ts';
-import { buildIngressPolicy } from './ingress-policy.ts';
+import {
+ __resetWarnedForwardedHeaderRefusalForTests,
+ buildIngressPolicy,
+} from './ingress-policy.ts';
import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';
import type { McpHttpHandler } from './mcp-http.ts';
import {
@@ -188,6 +191,10 @@ afterEach(async () => {
);
});
+beforeEach(() => {
+ __resetWarnedForwardedHeaderRefusalForTests();
+});
+
describe('mountMcpAndApi /mcp guard', () => {
test('rejects non-loopback Origin before the MCP handler runs', async () => {
let calls = 0;
@@ -284,6 +291,10 @@ describe('mountMcpAndApi /mcp guard', () => {
expect.objectContaining({ host: '127.0.0.1' }),
expect.stringContaining('refused proxied WS upgrade'),
);
+ expect(log.warn).toHaveBeenCalledWith(
+ { handler: 'ws-upgrade' },
+ expect.stringContaining('server.allowExternal'),
+ );
});
test('shares shutdown and keeps routing attached until the server closes', async () => {
diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.ts
index 2c9038d0c..e73afa8be 100644
--- a/packages/server/src/mcp-mount.ts
+++ b/packages/server/src/mcp-mount.ts
@@ -22,6 +22,7 @@ import {
isHostAdmitted,
isPeerAdmitted,
tripsForwardedHeaderTripwire,
+ warnForwardedHeaderRefusalOnce,
} from './ingress-policy.ts';
import type { PinoLogger } from './logger.ts';
import type { MaintenanceCoordinator } from './maintenance-coordinator.ts';
@@ -83,7 +84,7 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
const onRequest = (req: IncomingMessage, res: ServerResponse): void => {
const url = req.url?.split('?')[0];
- if (!admitRequestSurface(req, res, ingressPolicy, 'mcp-mount')) return;
+ if (!admitRequestSurface(req, res, ingressPolicy, 'mcp-mount', log)) return;
if (url?.startsWith('/api/')) {
hocuspocus
// biome-ignore lint/suspicious/noExplicitAny: Hocuspocus `hooks()` has no exported payload type for onRequest
@@ -195,6 +196,7 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
{ url: req.url, host: req.headers.host },
'[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_EXTERNAL_URL (or server.allowExternal + server.externalUrl in config)',
);
+ warnForwardedHeaderRefusalOnce(log, 'ws-upgrade');
}
socket.destroy();
};