Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.mdxindex 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.mdxindex 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.tsindex 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: zdiff --git a/packages/server/src/api-extension.test.ts b/packages/server/src/api-extension.test.tsindex 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.tsindex 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-aimport { 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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): MountMcpAndApiHandlconst 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();};