Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-8399 Wave 2 group 6: file-ops family native (#3940)

omar-inkeepff7ab457daeb
diff --git a/.changeset/upload-reserved-subtree-hardening.md b/.changeset/upload-reserved-subtree-hardening.md
new file mode 100644
index 000000000..6f8be0152
--- /dev/null
+++ b/.changeset/upload-reserved-subtree-hardening.md
@@ -0,0 +1,9 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Refuse writes routed into `.ok`/`.git` through the upload API, and stop blaming the caller for a missing content directory.
+
+`/api/upload` now rejects a destination inside a reserved subtree: a `parentDocName` that names or symlinks into `.ok`/`.git`, and a configured `content.attachmentFolderPath` that points there, both return `400 urn:ok:error:reserved-doc-name` where they previously wrote agent-loaded content into `.ok/skills/` with no validation. The check runs on the resolved destination directory, so a directory symlink planted in a cloned tree cannot route around it. The same canonical check now also covers the source path of a rename and the create-folder/duplicate-path/delete-path routes, and a `.ok/templates` directory that is itself a symlink is skipped when building the templates menu. The same canonical check now also gates `GET/PUT /api/folder-config`, the `/api/template` family including `/api/template/import`, and the folder-mode `GET /api/history?folder=`.
+
+Separately, a content directory that is missing at request time (deleted under a running server, unmounted volume) now surfaces as a 500 server error instead of a 400 path-escape blaming the request, and symlink escapes on create-folder, duplicate-path and delete-path return the documented `400 urn:ok:error:path-escape` instead of a generic 500.
diff --git a/packages/server/src/agent-write-summary.ts b/packages/server/src/agent-write-summary.ts
index acecc2d01..793780c7e 100644
--- a/packages/server/src/agent-write-summary.ts
+++ b/packages/server/src/agent-write-summary.ts
@@ -51,6 +51,16 @@ export type NormalizedSummary =
| { kind: 'invalid' }
| { kind: 'value'; value: string; truncatedFrom?: number };
+/**
+ * Wire shape of an attributed summary echoed back on write responses —
+ * the single owner of this alias so the attribution helpers in
+ * `api-extension.ts` and the route handlers that echo it cannot drift
+ * structurally. Mirrors the (loose) `SummaryResponseField` schema in
+ * `@inkeep/open-knowledge-core`; this alias stays exact-shaped so handlers
+ * don't inherit the schema's `[k: string]: unknown` catchall.
+ */
+export type SummaryResponse = { value: string; truncatedFrom?: number; hint?: string };
+
/**
* Normalize a raw body value into a truncated summary or a sentinel.
*
diff --git a/packages/server/src/api-extension.test.ts b/packages/server/src/api-extension.test.ts
index 0240b7ad8..b875e4e93 100644
--- a/packages/server/src/api-extension.test.ts
+++ b/packages/server/src/api-extension.test.ts
@@ -327,6 +327,20 @@ describe('handleUploadAsset', () => {
expect(existsSync(join(contentDir, 'docs', 'config-error.png'))).toBe(false);
});
+ test('a configured attachmentFolderPath naming .ok is refused at the resolved destination', async () => {
+ // `isValidAttachmentFolderPath` only rejects NUL/backslash/absolute/`..`,
+ // so `.ok/skills` is a legal config value (a planted `.ok/config.yml` in a
+ // cloned tree chooses it), and the request-field gate never sees it — the
+ // parentDocName here is innocuous. Pins the destination-side
+ // `reserved-destination` outcome in `storeUpload`.
+ attachmentFolderPath = '.ok/skills';
+ const res = await uploadImage(createPngBuffer(), 'planted.png', 'docs/guide.md');
+ const body = (await res.json()) as { type: string; status: number };
+ expect(res.status).toBe(400);
+ expect(body.type).toBe('urn:ok:error:reserved-doc-name');
+ expect(existsSync(join(contentDir, '.ok', 'skills', 'planted.png'))).toBe(false);
+ });
+
test('parent-dir placement keeps explicit sidebar folder drops in the target folder', async () => {
attachmentFolderPath = 'attachments';
const res = await uploadImage(createPngBuffer(), 'clip.png', 'docs/guide.md', 'parent-dir');
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 829304bd7..214850d81 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -10,7 +10,6 @@ import { type SpawnOptions, spawn } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import {
createReadStream,
- createWriteStream,
type Dirent,
existsSync,
lstatSync,
@@ -21,7 +20,6 @@ import {
realpathSync,
rmSync,
statSync,
- unlinkSync,
writeFileSync,
} from 'node:fs';
import { readdir, readFile, realpath, stat } from 'node:fs/promises';
@@ -54,10 +52,6 @@ import {
CheckoutResponseSchema,
CONFIG_DOC_NAME_OKIGNORE,
type ConfigDiagnosticsReport,
- CreateFolderRequestSchema,
- CreateFolderSuccessSchema,
- CreatePageRequestSchema,
- CreatePageSuccessSchema,
changedBlockRange,
colorFromSeed,
composeWithDerivedFrontmatter,
@@ -66,12 +60,8 @@ import {
DEFAULT_EMBEDDINGS_MODEL,
DEFAULT_LINKS_VALIDATION,
DEFAULT_LINTER_CONFIG,
- DeletePathRequestSchema,
- DeletePathSuccessSchema,
type DiskEditReconciledWarning,
type DocumentListEntry,
- DuplicatePathRequestSchema,
- DuplicatePathSuccessSchema,
detectFmRegion,
EDITOR_PROJECT_SKILL_ROOT,
type EditorId,
@@ -89,12 +79,10 @@ import {
InstallSkillRequestSchema,
InstallSkillSuccessSchema,
InvalidShareUrlError,
- instantiateDoc,
isManagedArtifactDocName,
isOpenKnowledgeSkillsSource,
isSkillInstallTarget,
LEGACY_SKILL_STORE_ROOT,
- LINKABLE_ASSET_EXTENSIONS,
type LinksValidationSetting,
LintConfigResponseSchema,
type LinterConfig,
@@ -133,8 +121,6 @@ import {
prependFrontmatter,
projectSkillContentDocName,
RENAMED_PACK_SKILLS,
- RenamePathRequestSchema,
- RenamePathSuccessSchema,
RollbackRequestSchema,
RollbackSuccessSchema,
readFmMap,
@@ -208,10 +194,6 @@ import {
TestRescanBacklinksSuccessSchema,
TestRescanFilesSuccessSchema,
TestResetSuccessSchema,
- TrashCleanupRequestSchema,
- TrashCleanupSuccessSchema,
- UploadAssetSuccessSchema,
- UploadRequestSchema,
USER_SKILL_EDITOR_IDS,
type ValidationDiagnostic,
} from '@inkeep/open-knowledge-core';
@@ -268,7 +250,11 @@ import {
prepareFrontmatterPatchParse,
snapshotBlocks,
} from './agent-sessions.ts';
-import { type NormalizedSummary, normalizeSummary } from './agent-write-summary.ts';
+import {
+ type NormalizedSummary,
+ normalizeSummary,
+ type SummaryResponse,
+} from './agent-write-summary.ts';
import { resolveBundledSkillDir } from './build-skill-zip.ts';
import { createCommentApi } from './comments/comment-api.ts';
import { CommentIndex } from './comments/comment-index.ts';
@@ -289,8 +275,6 @@ import {
composeSkillContent,
countBundleFiles,
} from './content/skills-write.ts';
-import { applySubstitution, todayIsoUtc } from './content/substitution.ts';
-import { resolveTemplatesAvailable } from './content/templates-resolver.ts';
import {
evaluateContentDivergence,
toContentDivergenceWarning,
@@ -309,7 +293,11 @@ import {
logFrontmatterRefusal,
respondFrontmatterMalformed,
} from './frontmatter-malformed-error.ts';
-import { assertNoSymlinkEscape } from './fs-safety.ts';
+import {
+ assertNoSymlinkEscape,
+ isContainmentRejection,
+ PathContainmentError,
+} from './fs-safety.ts';
import {
createInstalledAgentsProbe,
createOsProbe,
@@ -407,7 +395,6 @@ import {
} from './skill-projection.ts';
import { rewriteSkillRefsAcrossScope, type SkillRefRewrite } from './skill-ref-rename.ts';
import { assertRealpathWithinDir } from './symlink-guard.ts';
-import { HashingPassThrough, mintTempUploadPath } from './upload-streaming.ts';
/** Does the bundle at `dir` carry a `metadata.pack` marker in its frontmatter? */
function bundleSelfIdentifiesAsPack(dir: string): boolean {
@@ -431,7 +418,6 @@ import {
applyRenameMap,
BacklinkIndexRequiredError,
buildRenameMap,
- ManagedRenameCollisionError,
ManagedRenameDestinationExistsError,
ManagedRenameInvalidRequestError,
ManagedRenameMissingDocumentError,
@@ -439,7 +425,6 @@ import {
ManagedRenameSnapshotMissingError,
ManagedRenameSourceNotFoundError,
ManagedRenameSourceTypeMismatchError,
- SymlinkEscapeError,
} from './apply-managed-rename.ts';
import { composeAndWriteRawBody, type PrecomputedParse, replaceRawBody } from './bridge-intake.ts';
import type { BridgeDeriveLossReporter } from './bridge-loss-detector.ts';
@@ -464,7 +449,6 @@ import {
extensionlessDocTreePath,
forgetDocExtension,
getDocExtension,
- isSupportedAssetFile,
isSupportedDocFile,
registerDocExtension,
SUPPORTED_DOC_EXTENSIONS,
@@ -490,8 +474,6 @@ import {
import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';
import { isProjectRoot } from './fs/find-project-root.ts';
import {
- classifyFsPath,
- normalizeFsPath,
tracedCpSync,
tracedMkdirSync,
tracedRenameSync,
@@ -517,8 +499,13 @@ import {
errorResponse,
type HttpErrorStatus,
} from './http/error-response.ts';
+import {
+ createFileOpsRoutes,
+ type ManagedRenameRewrittenDoc,
+ type RenamedAssetMapping,
+ type RenamedDocMapping,
+} from './http/file-ops-routes.ts';
import { createFolderTemplateRoutes } from './http/folder-template-routes.ts';
-import { errnoCode } from './http/handler-utils.ts';
import { createHistoryRoutes } from './http/history-routes.ts';
import { assertSingleRouterOwnership, type NativeApiHandle } from './http/http-app.ts';
import { createLinkGraphRoutes } from './http/link-graph-routes.ts';
@@ -527,7 +514,7 @@ import { createLocalApiDispatch, type LocalApiDispatch } from './http/local-api-
import { methodRouter } from './http/method-router.ts';
import { createMetricsRoutes } from './http/metrics-routes.ts';
import { getRequestId } from './http/request-id.ts';
-import { validateBody, withValidation } from './http/request-validation.ts';
+import { withValidation } from './http/request-validation.ts';
import { createSeedRoutes } from './http/seed-routes.ts';
import { createSkillsReadRoutes } from './http/skills-read-routes.ts';
import { createSkillsShRoutes } from './http/skills-sh-routes.ts';
@@ -603,7 +590,7 @@ import {
} from './rename-log.ts';
import type { PairedWriteOrigin } from './server-observers.ts';
import { createAssetService } from './services/assets.ts';
-import { createFileOpsService } from './services/file-ops.ts';
+import { createFileOpsService, DuplicateNameExhaustedError } from './services/file-ops.ts';
import { createSearchService } from './services/search.ts';
import { createSkillImportService, type SkillImportOutcome } from './services/skill-import.ts';
import { createSkillInstallOpsService } from './services/skill-install-ops.ts';
@@ -881,203 +868,14 @@ export { sanitizeFilename } from './filename-sanitize.ts';
export { resolveUploadDestDir } from './services/assets.ts';
/**
- * Discriminator for write failures so the upload handler can surface a
- * specific error code (`collision-exhaustion` / `storage-full` /
- * `storage-readonly` / `storage-error`) instead of collapsing every
- * filesystem failure into a generic 500 "Failed to save file" response.
- * The code field is a stable part of the error envelope; the numeric
- * HTTP status differentiates transient-yet-retry (500) from full-disk
- * (507) per RFC 4918.
- */
-import {
- classifyUploadErrno,
- UploadWriteError,
- type UploadWriteReason,
- uploadStatusFor,
- uploadTitleFor,
-} from './upload-errors.ts';
-
-interface UploadResult {
- filename: string;
- mimeType: string;
- parentDocName: string;
- placement: string;
- tempPath: string;
- sha: string;
- byteLength: number;
-}
-
-/**
- * Stream multipart upload body to a tempfile while hashing on-the-fly.
- *
- * Replaces the buffer-to-memory pattern (chunks.push(chunk) +
- * Buffer.concat) with busboy's streaming 'file' event piped through a
- * HashingPassThrough Transform into createWriteStream(tempPath). Memory
- * becomes O(1); disk is the only bound.
- *
- * Error contract (typed via UploadWriteError.reason — URN-form ProblemType):
- * - urn:ok:error:malformed-upload: busboy 'error' (unparseable multipart, etc.)
- * - urn:ok:error:storage-full: ENOSPC / EDQUOT during the write stream
- * - urn:ok:error:storage-readonly: EROFS / EACCES / EPERM during the write stream
- * - urn:ok:error:storage-error: any other write-stream error
- *
- * On any error, the tempfile is best-effort unlinked before propagating.
+ * Shared errno table for disk-write failures (`storage-full` /
+ * `storage-readonly` / `storage-error`) — the agent-write persistence-failure
+ * surfaces below reuse the same mapping as the upload pipeline in
+ * `http/file-ops-routes.ts` so the two disk-failure classifications cannot
+ * drift. The numeric HTTP status differentiates transient-yet-retry (500)
+ * from full-disk (507) per RFC 4918.
*/
-function readUploadBody(req: IncomingMessage, projectDir: string): Promise<UploadResult> {
- return new Promise((resolveP, reject) => {
- let bb: MultipartParser;
- try {
- // `files: 1` caps the file part; `fields` + `fieldSize` cap non-file
- // surface so a flooded multipart can't buffer thousands of fields or a
- // multi-MB string field in memory before the upload body resolves. The
- // legitimate schema (agentId / docName / position / summary) is bounded
- // — short identifiers, never approaching 2 KB or 10 entries. The
- // ENAMETOOLONG-via-crafted-filename DoS path is closed by the 255-byte
- // ceiling in `sanitizeFilename` (the filesystem-portability layer);
- // busboy does not expose a header-section-size limit (only headerPairs
- // count), so the parsed-value cap is the right place.
- bb = createMultipartParser(req, { files: 1, fields: 10, fieldSize: 2 * 1024 });
- } catch (err) {
- reject(new UploadWriteError('urn:ok:error:malformed-upload', err));
- return;
- }
-
- let settled = false;
- let filename = 'upload';
- let mimeType = '';
- let parentDocName = '';
- let placement = '';
- let tempPath: string | undefined;
- let pipelineError: unknown;
- // Track whether the 'file' event ever fired. busboy emits 'close' as
- // soon as it finishes parsing the request body — but the file
- // pipeline (createWriteStream + HashingPassThrough) is async and may
- // still be running when 'close' fires. We must NOT resolve to an
- // empty UploadResult on 'close' when a file IS being processed; the
- // pipeline `.then()` is the legitimate resolver in that case. Only
- // the no-file path needs the 'close' fallback.
- let fileEventFired = false;
-
- // Mint the tempfile path lazily on the first 'file' event — busboy
- // can fire 'error' before any file arrives (e.g. missing boundary)
- // and we'd otherwise create a zero-byte tempfile for no reason.
-
- const fail = (reason: UploadWriteReason, cause: unknown) => {
- if (settled) return;
- settled = true;
- if (tempPath) {
- try {
- unlinkSync(tempPath);
- } catch {
- // best-effort; orphan sweep catches stragglers
- }
- }
- reject(cause instanceof UploadWriteError ? cause : new UploadWriteError(reason, cause));
- };
-
- const classifyWriteError = classifyUploadErrno;
-
- bb.on('field', (name, val) => {
- if (name === 'parentDocName') parentDocName = val;
- if (name === 'placement') placement = val;
- });
-
- bb.on('file', (_fieldname, file, info) => {
- fileEventFired = true;
- filename = info.filename || 'upload';
- mimeType = info.mimeType || '';
-
- // `mintTempUploadPath` does `tracedMkdirSync(.., { recursive: true })`
- // which can throw ENOSPC / EDQUOT / EROFS / EACCES / EPERM / EIO. An
- // uncaught throw here bubbles back through busboy's `_write` and
- // re-emits as `'error'`, which the listener below classifies as
- // `'urn:ok:error:malformed-upload'` (HTTP 400). That misleads operators triaging
- // a full disk into chasing a phantom client bug. Catch the sync
- // throw, classify via the same table the pipeline rejection uses,
- // and drain the file part so busboy can finish parsing the rest.
- let path: string;
- try {
- path = mintTempUploadPath(projectDir);
- } catch (err) {
- const nodeErr = err as NodeJS.ErrnoException;
- fail(classifyWriteError(nodeErr), err as Error);
- file.resume();
- return;
- }
- tempPath = path;
- const hasher = new HashingPassThrough();
- const writeStream = createWriteStream(path);
-
- pipeline(file, hasher, writeStream)
- .then(() => {
- if (settled) return;
- settled = true;
- resolveP({
- filename,
- mimeType,
- parentDocName,
- placement,
- tempPath: path,
- sha: hasher.digest(),
- byteLength: hasher.byteLength(),
- });
- })
- .catch((err) => {
- pipelineError = err;
- // Classify from the deepest write error if available; otherwise
- // treat as a generic storage-error. The unlink happens inside fail().
- const nodeErr = err as NodeJS.ErrnoException;
- fail(classifyWriteError(nodeErr), err);
- });
- });
-
- bb.on('error', (err) => {
- fail('urn:ok:error:malformed-upload', err);
- });
-
- // busboy's `close` (Writable, emitClose:true via @types/[email protected])
- // fires once busboy finishes parsing the request body. If by then
- // no `file` event ever fired, the request was a well-formed
- // multipart with fields-only (no file part) — resolve with a
- // synthetic empty UploadResult so the route handler's
- // `byteLength === 0` guard returns the standard 400 "No file
- // received." Without this hook the Promise never settles on fields-
- // only uploads and the connection hangs until Node's request
- // timeout fires (DoS).
- //
- // CRUCIAL: gate on `!fileEventFired`. If a file part IS present,
- // busboy emits 'close' as soon as it finishes parsing — but the
- // async write/hash pipeline below may still be running. Resolving
- // here would race the pipeline's legitimate resolveP and produce a
- // spurious empty result. Pipeline resolves win in that case.
- bb.on('close', () => {
- if (settled || pipelineError) return;
- if (fileEventFired) return;
- settled = true;
- resolveP({
- filename: '',
- mimeType: '',
- parentDocName,
- placement,
- tempPath: '',
- sha: '',
- byteLength: 0,
- });
- });
-
- // Guard the "client disconnected mid-stream" path. busboy never
- // reaches `_final` if the request aborts before the closing boundary,
- // so its `close` would not fire and the Promise would otherwise hang.
- req.on('close', () => {
- if (settled || pipelineError) return;
- if (!req.complete) {
- fail('urn:ok:error:malformed-upload', new Error('client disconnected'));
- }
- });
-
- req.pipe(bb);
- });
-}
+import { classifyUploadErrno, uploadStatusFor } from './upload-errors.ts';
/**
* Resolve a subdirectory path within a base directory, rejecting traversal attempts.
@@ -1799,26 +1597,11 @@ export async function walkContentDirForShowAll(
type ContentEntryKind = 'file' | 'folder';
-interface RenamedDocMapping {
- fromDocName: string;
- toDocName: string;
-}
-
-interface RenamedAssetMapping {
- fromPath: string;
- toPath: string;
-}
-
interface ManagedRenameRewriteSummary {
markdown: string;
rewrites: number;
}
-interface ManagedRenameRewrittenDoc {
- docName: string;
- rewrites: number;
-}
-
function isValidRelativeContentPath(path: string): boolean {
if (!path || path.startsWith('/') || path.includes('\\') || path.includes('\x00')) {
return false;
@@ -1827,28 +1610,6 @@ function isValidRelativeContentPath(path: string): boolean {
return path.split('/').every((segment) => segment && segment !== '.' && segment !== '..');
}
-/**
- * True when any `/`-separated segment of `path` is `.ok` or `.git`, at any
- * depth — nested `<folder>/.ok/` is a first-class OK shape (folder metadata +
- * templates), so a top-level-only check is not a boundary. Segments compare
- * case-insensitively: on the default case-insensitive macOS filesystem an
- * externally-addressed `.OK/x` IS `.ok/x`. Same segment walk as
- * `pathHasAlwaysSkipSegment` in content-filter.ts.
- */
-
-function isReservedSyntheticFolderPath(path: string): boolean {
- return (
- path === '__system__' ||
- path === '__config__' ||
- path === '__user__' ||
- path === '__local__' ||
- path.startsWith('__system__/') ||
- path.startsWith('__config__/') ||
- path.startsWith('__user__/') ||
- path.startsWith('__local__/')
- );
-}
-
function listAffectedDocNames(
index: ReadonlyMap<string, FileIndexEntry>,
kind: ContentEntryKind,
@@ -1898,7 +1659,7 @@ function requireNonEmptyDocName(
function resolveContentEntryPath(contentDir: string, kind: ContentEntryKind, path: string): string {
if (!isValidRelativeContentPath(path)) {
- throw new Error('path must be a relative content path');
+ throw new PathContainmentError('path must be a relative content path');
}
const resolvedContentDir = resolve(contentDir);
@@ -1911,7 +1672,7 @@ function resolveContentEntryPath(contentDir: string, kind: ContentEntryKind, pat
const fullPath = resolve(resolvedContentDir, relativePath);
if (fullPath !== resolvedContentDir && !fullPath.startsWith(`${resolvedContentDir}${sep}`)) {
- throw new Error('path must not escape content directory');
+ throw new PathContainmentError('path must not escape content directory');
}
assertNoSymlinkEscape(fullPath, resolvedContentDir);
@@ -1936,40 +1697,6 @@ function duplicateBasename(basename: string, attempt: number): string {
return attempt === 1 ? `${basename} copy` : `${basename} copy ${attempt}`;
}
-class DuplicateNameExhaustedError extends Error {
- constructor(readonly sourcePath: string) {
- super(`Could not find an available duplicate name for ${sourcePath}`);
- this.name = 'DuplicateNameExhaustedError';
- }
-}
-
-type DuplicatePathFilesystemProblem = {
- status: 500 | 507;
- type: Extract<ProblemType, 'urn:ok:error:storage-full' | 'urn:ok:error:storage-readonly'>;
- title: string;
-};
-
-function classifyDuplicatePathFilesystemProblem(
- err: unknown,
-): DuplicatePathFilesystemProblem | null {
- const code = errnoCode(err);
- if (code === 'ENOSPC' || code === 'EDQUOT') {
- return {
- status: 507,
- type: 'urn:ok:error:storage-full',
- title: 'Could not duplicate path because storage is full.',
- };
- }
- if (code === 'EPERM' || code === 'EACCES' || code === 'EROFS') {
- return {
- status: 500,
- type: 'urn:ok:error:storage-readonly',
- title: 'Could not duplicate path because storage is not writable.',
- };
- }
- return null;
-}
-
function docNameExistsWithAnySupportedExtension(contentDir: string, docName: string): boolean {
return resolveDocFilePath(contentDir, docName) !== null;
}
@@ -2007,12 +1734,12 @@ function docNameForFileOperationPath(contentDir: string, relPath: string): strin
function resolveDuplicateDocPath(contentDir: string, docName: string, extension: string): string {
if (!isValidRelativeContentPath(docName)) {
- throw new Error('path must be a relative content path');
+ throw new PathContainmentError('path must be a relative content path');
}
const resolvedContentDir = resolve(contentDir);
const fullPath = resolve(resolvedContentDir, `${docName}${extension}`);
if (fullPath !== resolvedContentDir && !fullPath.startsWith(`${resolvedContentDir}${sep}`)) {
- throw new Error('path must not escape content directory');
+ throw new PathContainmentError('path must not escape content directory');
}
assertNoSymlinkEscape(fullPath, resolvedContentDir);
return fullPath;
@@ -2093,56 +1820,6 @@ function collectFolderPaths(contentDir: string, folderPath: string): string[] {
return folders;
}
-/**
- * Probe disk for the actual on-disk extension of a file's docName, registering
- * it in the doc-extensions map if found. Closes a boot/watcher race where the
- * rename handler runs before the file watcher has observed the source — without
- * this, `getDocExtension()` returns the `.md` default, which silently defeats
- * `.mdx`-specific exclusion patterns and routes existence checks to the wrong
- * path. Iterating in `SUPPORTED_DOC_EXTENSIONS` precedence order ensures the
- * `.mdx` precedence rule is preserved when both files exist on disk.
- * Idempotent — `registerDocExtension` is a no-op when the higher-precedence
- * extension is already registered.
- */
-function probeAndRegisterSourceFileExtension(contentDir: string, fromPath: string): void {
- if (!isValidRelativeContentPath(fromPath)) return;
- const resolvedContentDir = resolve(contentDir);
- if (isSupportedDocFile(fromPath)) {
- const extensionless = stripDocExtension(fromPath);
- for (const ext of SUPPORTED_DOC_EXTENSIONS) {
- const candidate = resolve(resolvedContentDir, `${extensionless}${ext}`);
- if (
- candidate !== resolvedContentDir &&
- !candidate.startsWith(`${resolvedContentDir}${sep}`)
- ) {
- continue;
- }
- if (existsSync(candidate)) {
- registerDocExtension(extensionless, ext);
- }
- }
- const explicitCandidate = resolve(resolvedContentDir, fromPath);
- if (
- explicitCandidate !== resolvedContentDir &&
- explicitCandidate.startsWith(`${resolvedContentDir}${sep}`) &&
- existsSync(explicitCandidate)
- ) {
- registerDocExtension(extensionless, extname(fromPath));
- }
- return;
- }
- for (const ext of SUPPORTED_DOC_EXTENSIONS) {
- const candidate = resolve(resolvedContentDir, `${fromPath}${ext}`);
- if (candidate !== resolvedContentDir && !candidate.startsWith(`${resolvedContentDir}${sep}`)) {
- continue;
- }
- if (existsSync(candidate)) {
- registerDocExtension(fromPath, ext);
- return;
- }
- }
-}
-
function toGitRelativePath(projectDir: string, absolutePath: string): string | null {
const resolvedProjectDir = resolve(projectDir);
const resolvedPath = resolve(absolutePath);
@@ -3682,7 +3359,7 @@ export function createApiExtension(
if (error instanceof ManagedRenameSnapshotMissingError) {
return { status: 404, type: 'urn:ok:error:doc-not-found', error: withPeriod(error.message) };
}
- if (error instanceof SymlinkEscapeError) {
+ if (isContainmentRejection(error)) {
return { status: 400, type: 'urn:ok:error:path-escape', error: withPeriod(error.message) };
}
if (error instanceof BacklinkIndexRequiredError) {
@@ -3961,39 +3638,6 @@ export function createApiExtension(
return { rewrittenDocs, derivedMutations };
}
- function resolveExtensionlessAssetPath(assetPath: string): {
- path: string;
- ambiguous: boolean;
- } {
- // Filesystem-backed authority for extensionless asset targets; the client
- // canonicalizer is only a UX aid for dialogs and shell-trash paths.
- if (extname(assetPath)) return { path: assetPath, ambiguous: false };
-
- const slash = assetPath.lastIndexOf('/');
- const parent = slash === -1 ? '' : assetPath.slice(0, slash);
- const stem = slash === -1 ? assetPath : assetPath.slice(slash + 1);
- const parentPath = parent ? resolveContentEntryPath(contentDir, 'folder', parent) : contentDir;
-
- let entries: Dirent[];
- try {
- entries = readdirSync(parentPath, { withFileTypes: true });
- } catch (err) {
- const code = errnoCode(err);
- if (code === 'ENOENT' || code === 'ENOTDIR') {
- return { path: assetPath, ambiguous: false };
- }
- throw err;
- }
-
- const candidates = entries
- .filter((entry) => entry.isFile() && entry.name.startsWith(`${stem}.`))
- .map((entry) => (parent ? `${parent}/${entry.name}` : entry.name))
- .filter((candidate) => isSupportedAssetFile(candidate, LINKABLE_ASSET_EXTENSIONS));
-
- if (candidates.length === 1) return { path: candidates[0], ambiguous: false };
- return { path: assetPath, ambiguous: candidates.length > 1 };
- }
-
/**
* Enumerate the managed docNames physically present under a folder by
* walking disk, NOT the in-memory file index. The file index is populated
@@ -4918,9 +4562,10 @@ export function createApiExtension(
* `hint` is nested inside `summary` (not a sibling top-level key) so the
* truncation message always travels with the field it explains — this
* prevents naming collisions at the response root and tightens the coupling
- * between `truncatedFrom` and the human-readable explanation.
+ * between `truncatedFrom` and the human-readable explanation. The alias
+ * itself is owned by `agent-write-summary.ts` (imported at module top) so
+ * the native route handlers that echo it cannot drift structurally.
*/
- type SummaryResponse = { value: string; truncatedFrom?: number; hint?: string };
/**
* Pure response-shape derivation from a normalized summary — NO side effects.
@@ -8019,1316 +7664,96 @@ export function createApiExtension(
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 handleCreatePage = withValidation(
- CreatePageRequestSchema,
- async (_req, res, body) => {
- try {
- const bodyObj = body as unknown as Record<string, unknown>;
- // Identity boundary: only attribute when the caller explicitly supplies
- // agentId. UI-driven creates fall through to the loaded principal (if
- // any) or anonymous — never to a synthetic 'Claude' default. Mirrors
- // handleRollback / handleRenamePath.
- const actor = extractActorIdentity(bodyObj, getPrincipal);
- if (actor.kind === 'invalid-summary') {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
- handler: 'create-page',
- });
- return;
- }
-
- const filePath = body.path;
- if (!isSupportedDocFile(filePath)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'path must end with .md or .mdx.',
- { handler: 'create-page' },
- );
- return;
- }
- if (
- filePath.includes('..') ||
- filePath.startsWith('/') ||
- filePath.includes('\x00') ||
- filePath.includes('\\')
- ) {
- errorResponse(res, 400, 'urn:ok:error:path-escape', 'Invalid path.', {
- handler: 'create-page',
- detail: 'path must not contain .. or start with /',
- });
- return;
- }
- const resolvedContentDir = resolve(contentDir);
- const fullPath = resolve(resolvedContentDir, filePath);
- if (!isWithinDir(fullPath, resolvedContentDir)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:path-escape',
- 'path must not escape content directory.',
- { handler: 'create-page' },
- );
- return;
- }
- const candidateDocName = stripDocExtension(filePath);
- if (isSystemDoc(candidateDocName) || isConfigDoc(candidateDocName)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- `'${candidateDocName}' is a reserved document name.`,
- { handler: 'create-page' },
- );
- return;
- }
- // Reject managed-artifact + reserved-directory targets. Now that
- // `.ok/skills/**` is indexed/served content, a raw create-page into
- // `.ok/skills/<name>/SKILL.md` would write directly with ZERO skill-schema
- // validation (no name/description checks, no XML-tag ban) and surface as a
- // malformed phantom skill. Skills/templates must go through their own
- // validating write/install spines; every other `.ok/` child is excluded
- // from the content scope anyway. The reserved-path test catches raw
- // filesystem paths with a `.ok`/`.git` segment at any depth;
- // `isManagedArtifactDocName` catches the synthetic `__skill__/` /
- // `__template__/` doc-name forms.
- if (isReservedProjectStatePath(filePath) || isManagedArtifactDocName(candidateDocName)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- `'${candidateDocName}' is a reserved document name.`,
- {
- handler: 'create-page',
- detail:
- 'Cannot create a page inside .ok or .git — skills and templates are authored through their own validating flows.',
- },
- );
- return;
- }
- // Optional template parameter: when set, instantiate the new
- // doc from the resolved template's body (with {{date}} / {{user}}
- // substitution applied) instead of an empty file. Resolution walks
- // the parent folder's templates_available[] — local + inherited,
- // closest-wins.
- const templateName =
- typeof (body as Record<string, unknown>).template === 'string'
- ? ((body as Record<string, unknown>).template as string).trim()
- : '';
- let initialContent = '';
- let templateScopeForLog: 'local' | 'inherited' | undefined;
- if (templateName.length > 0) {
- if (!/^[A-Za-z0-9_-]+$/.test(templateName)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'Template name must match [A-Za-z0-9_-]+.',
- { handler: 'create-page' },
- );
- return;
- }
- const parentFolder = filePath.includes('/')
- ? filePath.slice(0, filePath.lastIndexOf('/'))
- : '';
- const available = resolveTemplatesAvailable(resolvedContentDir, parentFolder);
- const matched = available.find((t) => t.name === templateName);
- if (!matched) {
- const availableLabel =
- available.length === 0
- ? '(none)'
- : available.map((t) => `"${t.name}" (${t.scope})`).join(', ');
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- `Template "${templateName}" does not resolve for folder "${parentFolder || '(root)'}". Available: ${availableLabel}`,
- { handler: 'create-page' },
- );
- return;
- }
- const templateAbs = resolve(resolvedContentDir, matched.path);
- let templateRaw: string;
- try {
- templateRaw = readFileSync(templateAbs, 'utf-8');
- } catch (err) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- `Failed to read template at ${matched.path}.`,
- { handler: 'create-page', cause: err },
- );
- return;
- }
- // The new doc IS the template's starter content (doc-frontmatter +
- // markdown) with the `template:` identity stripped. `instantiateDoc`
- // normalizes single-block and legacy two-block templates the same way
- // and preserves `{{date}}`/`{{user}}` tokens verbatim for substitution.
- const templateStarter = instantiateDoc(templateRaw);
- // {{user}} substitutes the calling principal's display name; falls
- // back to empty string when no principal is loaded.
- const userDisplayName =
- actor.kind === 'agent' || actor.kind === 'principal' ? (actor.displayName ?? '') : '';
- initialContent = applySubstitution(templateStarter, {
- date: todayIsoUtc(),
- user: userDisplayName,
- });
- templateScopeForLog = matched.scope;
- }
-
- const docName = stripDocExtension(filePath);
- // Synchronous through recordContributor below: an async yield between
- // the write and the contributor recording lets a pending shadow-commit
- // timer drain the accumulator without this file's attribution.
- const createOutcome = fileOpsService.createPage({
- fullPath,
- docName,
- initialContent,
- });
- if (!createOutcome.ok) {
- errorResponse(res, 409, 'urn:ok:error:doc-already-exists', 'File already exists.', {
- handler: 'create-page',
- cause: createOutcome.cause,
- });
- return;
- }
- switch (actor.kind) {
- case 'agent':
- case 'principal':
- recordContributor(
- docName,
- actor.writerId,
- actor.displayName,
- actor.colorSeed,
- undefined,
- actor.actor,
- );
- break;
- case 'anonymous':
- // UI-driven create with no loaded principal — no contributor recorded.
- break;
- default: {
- const _exhaustive: never = actor;
- throw new Error(
- `Unhandled actor kind in handleCreatePage: ${String((_exhaustive as { kind?: unknown }).kind)}`,
- );
- }
- }
- // Best-effort for real (see the skill-put site): never hold a create
- // response on the derived-index command queue.
- void recordDerivedDocumentBestEffort(docName, initialContent, 'create-page');
- signalChannel?.('files');
- if (templateScopeForLog !== undefined) {
- // Cardinality-bounded structured event — `templateScope` is one of
- // two values; `templateName` is bounded by the user's actual
- // templates. Mirrors the structured-event style in activity-log.ts.
- console.warn(
- JSON.stringify({
- event: 'template-instantiate',
- templateName,
- templateScope: templateScopeForLog,
- docName,
- }),
- );
- }
- successResponse(res, 200, CreatePageSuccessSchema, { docName }, { handler: 'create-page' });
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to create page.', {
- handler: 'create-page',
- cause: e,
- });
- }
- },
- { handler: 'create-page', method: 'POST' },
- );
-
- 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 handleCreateFolder = withValidation(
- CreateFolderRequestSchema,
- async (_req, res, body) => {
- try {
- const bodyObj = body as unknown as Record<string, unknown>;
- const actor = extractActorIdentity(bodyObj, getPrincipal);
- if (actor.kind === 'invalid-summary') {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
- handler: 'create-folder',
- });
- return;
- }
- const folderPath = body.path;
- if (!isValidRelativeContentPath(folderPath)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'path must be a relative content path.',
- { handler: 'create-folder' },
- );
- return;
- }
- if (isReservedProjectStatePath(folderPath)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- '.ok and .git are reserved directories.',
- { handler: 'create-folder' },
- );
- return;
- }
- if (contentFilter?.isDirExcluded(folderPath)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'Destination folder is excluded by the workspace content config.',
- { handler: 'create-folder' },
- );
- return;
- }
-
- const outcome = fileOpsService.createFolder(folderPath);
- if (!outcome.ok) {
- errorResponse(res, 409, 'urn:ok:error:doc-already-exists', 'Folder already exists.', {
- handler: 'create-folder',
- });
- return;
- }
- successResponse(
- res,
- 200,
- CreateFolderSuccessSchema,
- { path: folderPath },
- { handler: 'create-folder' },
- );
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to create folder.', {
- handler: 'create-folder',
- cause: e,
- });
- }
- },
- { handler: 'create-folder', method: 'POST' },
- );
-
- const handleDuplicatePath = withValidation(
- DuplicatePathRequestSchema,
- async (_req, res, body) => {
- try {
- const bodyObj = body as unknown as Record<string, unknown>;
- const actor = extractActorIdentity(bodyObj, getPrincipal);
- if (actor.kind === 'invalid-summary') {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
- handler: 'duplicate-path',
- });
- return;
- }
-
- const { kind } = body;
- const requestedPath = body.path;
- const requestedDocName = kind === 'file' ? stripDocExtension(requestedPath) : requestedPath;
- if (!isValidRelativeContentPath(requestedPath)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'path must be a relative content path.',
- { handler: 'duplicate-path' },
- );
- return;
- }
- if (
- isReservedProjectStatePath(requestedPath) ||
- (kind === 'file' && (isSystemDoc(requestedDocName) || isConfigDoc(requestedDocName))) ||
- (kind === 'folder' && isReservedSyntheticFolderPath(requestedPath))
- ) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- 'Reserved paths cannot be duplicated.',
- { handler: 'duplicate-path' },
- );
- return;
- }
-
- if (kind === 'file') {
- probeAndRegisterSourceFileExtension(contentDir, requestedPath);
- }
-
- const outcome = await fileOpsService.duplicatePath(kind, requestedPath, requestedDocName);
- if (!outcome.ok) {
- switch (outcome.kind) {
- case 'not-found':
- errorResponse(res, 404, 'urn:ok:error:doc-not-found', `${kind} does not exist.`, {
- handler: 'duplicate-path',
- });
- return;
- case 'type-mismatch':
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- `Target path is not a ${kind}.`,
- { handler: 'duplicate-path' },
- );
- return;
- case 'conflict':
- respondDocInConflict(
- res,
- new DocInConflictError({ file: outcome.file }),
- 'duplicate-path',
- );
- return;
- case 'destination-excluded':
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- kind === 'file'
- ? 'Duplicated document destination is excluded by the project content config.'
- : 'Duplicated folder destination is excluded by the project content config.',
- { handler: 'duplicate-path' },
- );
- return;
- case 'already-exists':
- errorResponse(
- res,
- 409,
- 'urn:ok:error:doc-already-exists',
- `A ${kind} at the duplicate destination already exists.`,
- { handler: 'duplicate-path', cause: outcome.cause },
- );
- return;
- default: {
- const _exhaustive: never = outcome;
- throw new Error(
- `Unhandled duplicate outcome: ${String((_exhaustive as { kind?: unknown }).kind)}`,
- );
- }
- }
- }
- const { duplicatedPath, duplicatedDocNames } = outcome;
-
- switch (actor.kind) {
- case 'agent':
- case 'principal':
- for (const docName of duplicatedDocNames) {
- recordContributor(
- docName,
- actor.writerId,
- actor.displayName,
- actor.colorSeed,
- undefined,
- actor.actor,
- );
- }
- break;
- case 'anonymous':
- break;
- default: {
- const _exhaustive: never = actor;
- throw new Error(
- `Unhandled actor kind in handleDuplicatePath: ${String((_exhaustive as { kind?: unknown }).kind)}`,
- );
- }
- }
-
- signalChannel?.('files');
- successResponse(
- res,
- 200,
- DuplicatePathSuccessSchema,
- { kind, path: duplicatedPath, duplicatedDocNames },
- { handler: 'duplicate-path' },
- );
- } catch (e) {
- if (e instanceof DuplicateNameExhaustedError) {
- errorResponse(
- res,
- 409,
- 'urn:ok:error:doc-already-exists',
- 'All available duplicate name slots are occupied for this path.',
- { handler: 'duplicate-path', cause: e },
- );
- return;
- }
- const filesystemProblem = classifyDuplicatePathFilesystemProblem(e);
- if (filesystemProblem) {
- errorResponse(
- res,
- filesystemProblem.status,
- filesystemProblem.type,
- filesystemProblem.title,
- { handler: 'duplicate-path', cause: e },
- );
- return;
- }
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to duplicate path.', {
- handler: 'duplicate-path',
- cause: e,
- });
- }
- },
- { handler: 'duplicate-path', method: 'POST' },
- );
-
- const handleRenamePath = withValidation(
- RenamePathRequestSchema,
- async (_req, res, body) => {
- try {
- const bodyObj = body as unknown as Record<string, unknown>;
- const actor = extractActorIdentity(bodyObj, getPrincipal);
- if (actor.kind === 'invalid-summary') {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
- handler: 'rename-path',
- });
- return;
- }
- const { kind, fromPath, toPath } = body;
- if (!isValidRelativeContentPath(fromPath) || !isValidRelativeContentPath(toPath)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'Paths must be relative content paths.',
- { handler: 'rename-path' },
- );
- return;
- }
- if (
- kind === 'file' &&
- (isSystemDoc(fromPath) ||
- isSystemDoc(toPath) ||
- isConfigDoc(fromPath) ||
- isConfigDoc(toPath))
- ) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- 'Reserved document names cannot be renamed.',
- { handler: 'rename-path' },
- );
- return;
- }
- // Reject paths with a `.ok` or `.git` segment at any depth — root
- // `.ok/` holds OK config (`config.yml`, `frontmatter.yml`,
- // `templates/`) plus the per-machine `local/` runtime subtree
- // (server.lock, principal.json, cache, etc.), and nested
- // `<folder>/.ok/` holds folder metadata + templates. Symmetric with
- // the `__system__` carve-out. The `AGENTS.md` file inside `.ok/` is a
- // tracked content file by design, but a rename TO or FROM these
- // directories would clobber OK bookkeeping.
- if (isReservedProjectStatePath(fromPath) || isReservedProjectStatePath(toPath)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- '.ok and .git are reserved directories.',
- {
- handler: 'rename-path',
- },
- );
- return;
- }
- if (fromPath === toPath) {
- successResponse(
- res,
- 200,
- RenamePathSuccessSchema,
- { renamed: [], renamedAssets: [], rewrittenDocs: [] },
- { handler: 'rename-path' },
- );
- return;
- }
- const operationKind =
- kind === 'asset' && isSupportedDocFile(fromPath) && isSupportedDocFile(toPath)
- ? 'file'
- : kind;
- if (operationKind === 'asset') {
- let result: {
- renamedAssets: RenamedAssetMapping[];
- rewrittenDocs: ManagedRenameRewrittenDoc[];
- };
- try {
- result =
- isSupportedDocFile(fromPath) && !isSupportedDocFile(toPath)
- ? await _performDocumentToFileRename(fromPath, toPath)
- : await _performAssetRename(fromPath, toPath);
- } catch (err) {
- if (err instanceof DocInConflictError) {
- respondDocInConflict(res, err, 'rename-path');
- return;
- }
- const { status, type, error } = toManagedRenamePublicError(err);
- errorResponse(res, status, type, error, {
- handler: 'rename-path',
- cause: err,
- });
- return;
- }
-
- if (result.renamedAssets.length > 0) {
- invalidateReferencedAssetsCache();
- }
-
- let summaryResponse: SummaryResponse | undefined;
- if (result.renamedAssets.length > 0 && result.rewrittenDocs.length > 0) {
- const subject = `Renamed asset ${fromPath} → ${toPath}`;
- summaryResponse = attributeRenameWriteToActor(
- actor,
- subject,
- result.rewrittenDocs.map(({ docName }) => ({ docName, subject })),
- {
- context: 'handleRenamePath asset branch',
- onAnonymous: () => {
- log.debug(
- {
- kind: 'asset',
- fromPath,
- toPath,
- affectedDocs: result.rewrittenDocs.length,
- affectedAssets: result.renamedAssets.length,
- },
- '[rename-path] anonymous actor; no contributor recorded (no agentId in body and getPrincipal() returned null)',
- );
- },
- },
- );
- }
- renameAttributionCounter().add(1, {
- kind: 'rename-asset',
- attribution_kind: actor.kind,
- });
-
- if (flushContributors) {
- try {
- await flushContributors();
- } catch (flushErr) {
- log.warn(
- { err: flushErr },
- '[rename-path] flushContributors failed after asset rename (commitSha backfill may be deferred)',
- );
- }
- }
-
- successResponse(
- res,
- 200,
- RenamePathSuccessSchema,
- {
- renamed: [],
- renamedAssets: result.renamedAssets,
- rewrittenDocs: result.rewrittenDocs,
- ...(summaryResponse ? { summary: summaryResponse } : {}),
- },
- { handler: 'rename-path' },
- );
- return;
- }
- // Register the source's actual on-disk extension before downstream
- // checks so admission, conflict checks, and existsSync probes all see
- // the right value when the file watcher hasn't yet observed the source
- // (boot race).
- if (operationKind === 'file') {
- probeAndRegisterSourceFileExtension(contentDir, fromPath);
- }
- // Conflict-aware refusal. Renaming a conflicted source doc would
- // shift the file path while the merge stages still live at the
- // old path — the disk-watcher → reconcile loop would then see two
- // paths racing the same content. For a folder rename we ALSO
- // refuse if any affected child carries 'conflict': the per-doc
- // rewrite spine (`applyManagedRenameMapToLoadedDocument` →
- // `composeAndWriteRawBody`) is a sibling primitive to
- // `applyAgentMarkdownWrite` and does NOT inherit its gate.
- // Mirrors handleDeletePath's affected-docs scan.
- //
- // Dual-source check: hocuspocus.documents.get() returns undefined
- // for docs evicted from memory (e.g., after boot-time
- // restoreLifecycleFromConflictsJson disconnects them). Falling back
- // to ConflictStore via SyncEngine catches that eviction race —
- // mirrors the dual-source pattern used in handleSyncConflictContent's
- // 404 gate.
- // Enumerate from disk (not the lagging file index) so the conflict
- // pre-check sees every on-disk child of the folder — same root cause
- // as the spine's `affectedDocNames`.
- const renameAffectedDocNames =
- operationKind === 'file'
- ? [docNameForFileOperationPath(contentDir, fromPath)]
- : listManagedDocNamesUnderFolderFromDisk(
- resolveContentEntryPath(contentDir, 'folder', fromPath),
- );
- const renameEngine = getSyncEngine?.();
- const renameTrackedFiles = new Set(
- renameEngine ? renameEngine.getConflicts().map((c) => c.file) : [],
- );
- for (const affected of renameAffectedDocNames) {
- const affectedDocName = affected;
- const doc = hocuspocus.documents.get(affectedDocName);
- const filePath = docNameToRelativePath(affectedDocName);
- const conflictedByLifecycle = doc !== undefined && isDocInConflict(doc);
- const conflictedByStore = renameTrackedFiles.has(filePath);
- if (conflictedByLifecycle || conflictedByStore) {
- respondDocInConflict(res, new DocInConflictError({ file: filePath }), 'rename-path');
- return;
- }
- }
-
- if (contentFilter) {
- // Mirror `resolveContentEntryPath`'s explicit-extension detection so
- // a destination like `bar.mdx` is checked verbatim instead of as
- // `bar.mdx.md` (which would miss `*.mdx` exclusion patterns).
- const sourceExt = isSupportedDocFile(fromPath)
- ? extname(fromPath)
- : getDocExtension(fromPath);
- const excluded =
- operationKind === 'file'
- ? contentFilter.isExcluded(
- isSupportedDocFile(toPath) ? toPath : `${toPath}${sourceExt}`,
- )
- : contentFilter.isDirExcluded(toPath);
- if (excluded) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- `Destination ${operationKind === 'file' ? 'document' : 'folder'} is excluded by the project content config.`,
- { handler: 'rename-path' },
- );
- return;
- }
- }
-
- // Thread the actor identity through to the rewrite spine so the
- // rename log entry carries the right writerId. Anonymous → service
- // writer fallback is handled inside the spine.
- const renameActor =
- actor.kind === 'agent' || actor.kind === 'principal'
- ? {
- writerId: actor.writerId,
- displayName: actor.displayName,
- colorSeed: actor.colorSeed,
- actorMetadata: actor.actor,
- }
- : undefined;
-
- let result: {
- renamed: RenamedDocMapping[];
- renamedAssets: RenamedAssetMapping[];
- rewrittenDocs: ManagedRenameRewrittenDoc[];
- };
- try {
- result = await _performManagedRenameForDocs(
- fromPath,
- toPath,
- operationKind,
- renameActor ? { actor: renameActor } : {},
- );
- } catch (err) {
- if (err instanceof ManagedRenameCollisionError) {
- errorResponse(res, 409, 'urn:ok:error:doc-already-exists', withPeriod(err.message), {
- handler: 'rename-path',
- extensions: { colliding: err.colliding },
- cause: err,
- });
- return;
- }
- throw err;
- }
-
- if (result.renamed.length === 0 && result.renamedAssets.length === 0) {
- successResponse(
- res,
- 200,
- RenamePathSuccessSchema,
- { renamed: [], renamedAssets: [], rewrittenDocs: [] },
- { handler: 'rename-path' },
- );
- return;
- }
-
- if (result.renamedAssets.length > 0) {
- invalidateReferencedAssetsCache();
- }
-
- let summaryResponse: SummaryResponse | undefined;
- const logicalRenames = result.renamed.filter(
- ({ fromDocName, toDocName }) => fromDocName !== toDocName,
- );
- if (logicalRenames.length > 0) {
- summaryResponse = attributeRenameWriteToActor(
- actor,
- `Renamed ${fromPath} → ${toPath}`,
- logicalRenames.map(({ fromDocName, toDocName }) => ({
- docName: toDocName,
- subject: formatRenameSubject(fromDocName, toDocName),
- })),
- {
- context: 'handleRenamePath',
- onAnonymous: () => {
- log.debug(
- { kind, fromPath, toPath, affectedDocs: result.renamed.length },
- '[rename-path] anonymous actor — no contributor recorded (no agentId in body and getPrincipal() returned null)',
- );
- },
- },
- );
- }
- renameAttributionCounter().add(1, {
- kind: `rename-${operationKind}`,
- attribution_kind: actor.kind,
- });
-
- // Flush pending contributors so the rename-log entry's commitSha is
- // backfilled by `commitToWipRefInner` BEFORE the API responds.
- // Without this, a "pure rename without subsequent edit" leaves
- // commitSha as '' until the next persistence drain (which may never
- // happen) — the timeline rename-history mitigation depends on
- // commitSha being a real 40-char SHA at read time. Mirrors the
- // pattern at handleRollback (post-rollback flushContributors call).
- if (flushContributors) {
- try {
- await flushContributors();
- } catch (flushErr) {
- log.warn(
- { err: flushErr },
- '[rename-path] flushContributors failed (commitSha backfill may be deferred)',
- );
- }
- }
-
- successResponse(
- res,
- 200,
- RenamePathSuccessSchema,
- {
- renamed: result.renamed,
- renamedAssets: result.renamedAssets,
- rewrittenDocs: result.rewrittenDocs,
- ...(summaryResponse ? { summary: summaryResponse } : {}),
- },
- { handler: 'rename-path' },
- );
- } catch (e) {
- const { status, type, error } = toManagedRenamePublicError(e);
- errorResponse(res, status, type, error, {
- handler: 'rename-path',
- cause: e,
- });
- }
- },
- { handler: 'rename-path', method: 'POST' },
- );
-
- const handleDeletePath = withValidation(
- DeletePathRequestSchema,
- async (_req, res, body) => {
- try {
- extractAgentIdentity(body as unknown as Record<string, unknown>); // attribution threading
- const { kind, path } = body;
- if (!isValidRelativeContentPath(path)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'path must be a relative content path.',
- { handler: 'delete-path' },
- );
- return;
- }
- const assetResolution =
- kind === 'asset' ? resolveExtensionlessAssetPath(path) : { path, ambiguous: false };
- if (assetResolution.ambiguous) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'Asset path without an extension matches multiple files.',
- { handler: 'delete-path' },
- );
+ 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;
}
- const operationPath = assetResolution.path;
- const operationKind = kind === 'asset' && isSupportedDocFile(operationPath) ? 'file' : kind;
- if (operationKind === 'file') {
- probeAndRegisterSourceFileExtension(contentDir, operationPath);
- }
- if (isReservedProjectStatePath(operationPath)) {
+ if (resolution.size > TEXT_VIEW_MAX_BYTES) {
errorResponse(
res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- '.ok and .git are reserved directories.',
- { handler: 'delete-path' },
+ 413,
+ 'urn:ok:error:payload-too-large',
+ `File exceeds the ${TEXT_VIEW_MAX_BYTES}-byte text-viewer cap.`,
+ { handler: 'asset-text' },
);
return;
}
-
- const outcome = await fileOpsService.deletePath(operationKind, operationPath);
- if (!outcome.ok) {
- if (outcome.kind === 'not-found') {
- errorResponse(
- res,
- 404,
- 'urn:ok:error:doc-not-found',
- `${operationKind} does not exist.`,
- { handler: 'delete-path' },
- );
- } else if (outcome.kind === 'type-mismatch') {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- `Target path is not a ${operationKind}.`,
- { handler: 'delete-path' },
- );
- } else {
- respondDocInConflict(
- res,
- new DocInConflictError({ file: outcome.file }),
- 'delete-path',
- );
- }
- return;
- }
- successResponse(
- res,
- 200,
- DeletePathSuccessSchema,
- { deletedDocNames: outcome.deletedDocNames },
- { handler: 'delete-path' },
- );
+ 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', 'Failed to delete path.', {
- handler: 'delete-path',
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'asset-text',
cause: e,
});
}
},
- { handler: 'delete-path', method: 'POST' },
+ { handler: 'asset-text', method: 'GET', skipBodyParse: true },
);
- // Two-step Trash flow: the renderer calls
- // `bridge.shell.trashItem` (Step 1) which moves the file to ~/.Trash via
- // `shell.trashItem`. On success, the renderer POSTs here (Step 2) to
- // synchronously cleanup server-side state — close Hocuspocus docs, mark
- // `recentlyRemovedDocs`, purge the file index, broadcast CC1 files.
- // Does NOT touch disk (the file is already gone from contentDir).
- //
- // Idempotent: if the file-watcher already processed the OS-level deletion
- // between Step 1 and Step 2, `listAffectedDocNames` returns an empty array
- // and the handler returns 200 with `deletedDocNames: []` rather than 404 —
- // the desired end state (gone) is still true.
- const handleTrashCleanup = withValidation(
- TrashCleanupRequestSchema,
- async (_req, res, body) => {
- return withSpan(
- 'ok.fs.trash_cleanup',
- {
- attributes: {
- 'ok.cleanup.kind': body.kind,
- 'ok.cleanup.path': normalizeFsPath(body.path),
- 'ok.cleanup.path.role': classifyFsPath(body.path),
- },
- },
- async () => {
- try {
- const bodyObj = body as unknown as Record<string, unknown>;
- const actor = extractActorIdentity(bodyObj, getPrincipal);
- if (actor.kind === 'invalid-summary') {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
- handler: 'trash-cleanup',
- });
- return;
- }
- const { kind, path } = body;
- if (!isValidRelativeContentPath(path)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'path must be a relative content path.',
- { handler: 'trash-cleanup' },
- );
- return;
- }
- const operationKind = kind === 'asset' && isSupportedDocFile(path) ? 'file' : kind;
- const operationDocName = stripDocExtension(path);
- if (operationKind === 'file') {
- probeAndRegisterSourceFileExtension(contentDir, path);
- }
- // Defense in depth — synthetic docs never reach disk so cleanup
- // against them is meaningless; mirrors the gate handleDeletePath
- // implicitly enforces via `resolveContentEntryPath` + existsSync.
- // Folder kind is checked separately: a `kind: 'folder', path:
- // '__config__'` payload would otherwise reach listAffectedDocNames
- // + captureAndCloseDocuments on the synthetic config docs inside
- // that namespace before the per-doc guard at the recently-removed
- // loop fires.
- const isReservedFolder =
- operationKind === 'folder' && isReservedSyntheticFolderPath(path);
- if (
- (operationKind === 'file' &&
- (isSystemDoc(operationDocName) || isConfigDoc(operationDocName))) ||
- isReservedFolder ||
- isReservedProjectStatePath(path)
- ) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- `'${path}' is a reserved document name.`,
- { handler: 'trash-cleanup' },
- );
- return;
- }
- const { deletedDocNames } = await fileOpsService.trashCleanup(
- operationKind,
- path,
- operationDocName,
- 'handleTrashCleanup',
- );
- successResponse(
- res,
- 200,
- TrashCleanupSuccessSchema,
- { deletedDocNames },
- { handler: 'trash-cleanup' },
- );
- } catch (e) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'Failed to clean up after trash.',
- {
- handler: 'trash-cleanup',
- cause: e,
- },
- );
- }
- },
- );
+ 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);
},
- { handler: 'trash-cleanup', method: 'POST' },
- );
-
- async function handleUploadAsset(req: IncomingMessage, res: ServerResponse): Promise<void> {
- if (req.method !== 'POST') {
- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
- handler: 'upload-asset',
- extraHeaders: { Allow: 'POST' },
- });
- return;
- }
-
- let uploadResult: UploadResult | undefined;
- try {
- uploadResult = await readUploadBody(req, projectDir ?? contentDir);
- } catch (e) {
- // All body-parse failures land as UploadWriteError with a URN-form
- // reason. Tempfile cleanup is handled inside readUploadBody's error
- // path. Anonymous emit (no extractAgentIdentity yet) is semantically
- // OK — no Y.Doc mutation has been attempted.
- if (e instanceof UploadWriteError) {
- errorResponse(res, uploadStatusFor(e.reason), e.reason, uploadTitleFor(e.reason), {
- handler: 'upload-asset',
- cause: e,
- });
- return;
- }
- errorResponse(res, 400, 'urn:ok:error:malformed-upload', 'Failed to parse upload.', {
- handler: 'upload-asset',
- cause: e,
- });
- return;
- }
-
- const {
- filename,
- tempPath,
- sha,
- byteLength,
- parentDocName: rawParentDocName,
- placement: rawPlacement,
- } = uploadResult;
-
- // Belt-and-braces cleanup: if anything below this point errors or
- // early-returns, the tempfile must go away. Every early-return path
- // below that does NOT consume tempPath via linkTempToFinal* runs this.
- const cleanupTempfile = () => {
- if (existsSync(tempPath)) {
- try {
- unlinkSync(tempPath);
- } catch {
- // best-effort; orphan sweep reaps stragglers
- }
- }
- };
-
- // Validate metadata fields (parentDocName etc.) via the shared
- // `validateBody` middleware. Body-shape failure emits 400
- // `urn:ok:error:invalid-request` BEFORE `extractAgentIdentity` runs —
- // an anonymous response is semantically correct here because no Y.Doc
- // mutation is attempted. Mirrors `withValidation`'s policy for JSON
- // handlers.
- const validated = validateBody(
- UploadRequestSchema,
- { parentDocName: rawParentDocName, placement: rawPlacement || undefined },
- res,
- {
- handler: 'upload-asset',
- },
- );
- if (!validated.ok) {
- cleanupTempfile();
- return;
- }
- const { parentDocName, placement } = validated.value;
-
- // Identity extracted from query params (multipart body precludes JSON).
- // Capture agentId / agentName so structured upload logs carry
- // attribution — mirrors precedent #24/#25 and lets operators trace
- // unexpected file-creation events back to the originating agent
- // during incident investigation. Both fields follow bounded shapes
- // (agentId matches AGENT_ID_RE; agentName is sanitized) so they
- // remain cardinality-safe for log indexing.
- //
- // CRUCIAL: identity extraction must precede every SEMANTIC error
- // emission below (path-escape, no-file-received, storage-error). Body-
- // shape errors above (urn:ok:error:invalid-request, urn:ok:error:malformed-upload)
- // are anonymous because no Y.Doc mutation is attempted. The
- // attribution-sweep-coverage ordering check enforces this distinction
- // (precedent #24).
- const { agentId, agentName } = extractAgentIdentity(
- Object.fromEntries(new URL(req.url ?? '', 'http://localhost').searchParams.entries()),
- );
-
- if (byteLength === 0) {
- cleanupTempfile();
- errorResponse(res, 400, 'urn:ok:error:no-file-received', 'No file received.', {
- handler: 'upload-asset',
- });
- return;
- }
-
- // Reject path-escape attempts.
- if (
- parentDocName.includes('\x00') ||
- parentDocName.includes('..') ||
- parentDocName.startsWith('/')
- ) {
- cleanupTempfile();
- errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {
- handler: 'upload-asset',
- });
- return;
- }
-
- const outcome = await assetService.storeUpload({
- tempPath,
- sha,
- byteLength,
- filename,
- parentDocName,
- placement,
- });
- if (outcome.ok) {
- log.info(
- {
- event: 'upload',
- endpoint: req.url ?? '/api/upload',
- agentId,
- agentName,
- dedup: outcome.deduped,
- mime: outcome.mime,
- size: byteLength,
- // `destPath` is the contentDir-relative asset path. High-
- // cardinality by nature — fine as a log field consumed by text-
- // search / by-incident filtering; NEVER promote it to a metric
- // label (per-asset label explosion).
- destPath: outcome.path,
- httpStatus: 200,
- },
- outcome.deduped ? '[upload] dedup hit' : '[upload] write ok',
- );
- // RFC 9457 §3 success path: drop the `ok: true` wrapper. Wire shape
- // is `{ src, path, deduped }`; clients discriminate on HTTP status.
- successResponse(
- res,
- 200,
- UploadAssetSuccessSchema,
- { src: outcome.src, path: outcome.path, deduped: outcome.deduped },
- { handler: 'upload-asset' },
- );
- return;
- }
- switch (outcome.kind) {
- case 'config-error':
- log.error(
- { err: outcome.cause },
- '[upload] project config has invalid content.attachmentFolderPath',
- );
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'Server configuration error: invalid attachment folder path.',
- { handler: 'upload-asset', cause: outcome.cause },
- );
- return;
- case 'invalid-attachment-folder':
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid attachment folder path.', {
- handler: 'upload-asset',
- });
- return;
- case 'path-escape':
- errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {
- handler: 'upload-asset',
- ...(outcome.cause === undefined ? {} : { cause: outcome.cause }),
- });
- return;
- case 'dest-validation-error':
- log.error(
- { err: outcome.cause, destDir: outcome.destDir },
- '[upload] failed to validate destination directory',
- );
- errorResponse(res, 500, 'urn:ok:error:storage-error', 'Storage error.', {
- handler: 'upload-asset',
- cause: outcome.cause,
- });
- return;
- case 'mkdir-failed':
- errorResponse(
- res,
- uploadStatusFor(outcome.reason),
- outcome.reason,
- uploadTitleFor(outcome.reason),
- {
- handler: 'upload-asset',
- cause: outcome.cause,
- detail: 'failed to create attachment directory',
- },
- );
- return;
- case 'write-failed':
- log.error(
- {
- event: 'upload',
- endpoint: req.url ?? '/api/upload',
- requestId: getRequestId(req),
- agentId,
- agentName,
- filename: outcome.filename,
- size: byteLength,
- reason: outcome.reason,
- httpStatus: uploadStatusFor(outcome.reason),
- err: outcome.cause,
- },
- '[upload] write failed',
- );
- errorResponse(
- res,
- uploadStatusFor(outcome.reason),
- outcome.reason,
- uploadTitleFor(outcome.reason),
- { handler: 'upload-asset', cause: outcome.cause },
- );
- return;
- }
- }
+ 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,
+ });
// ─── Local-op relay endpoints (/api/local-op/*) ─────────────────────────────
// loopback + origin + path safety + URL allowlist + concurrency=1 + 10-min timeout
@@ -11521,8 +9946,46 @@ export function createApiExtension(
candidateAbs !== resolvedContentDir &&
!candidateAbs.startsWith(`${resolvedContentDir}${sep}`)
) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Path escapes content directory.', {
+ errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escapes content directory.', {
+ handler,
+ });
+ return null;
+ }
+ // Canonical containment on top of the lexical prefix check above, which a
+ // symlinked directory defeats (`notes -> /outside` keeps every lexical
+ // check green while the write lands outside the root). One gate here
+ // covers both consumer families — the folder-template routes AND the
+ // folder-mode history arm — because the writers behind it
+ // (`applyFolderFrontmatterPatch`, the template write/delete/move helpers)
+ // mkdir and write under the validated folder without re-checking.
+ // The asserts anchor on the components the writers actually TOUCH:
+ // `<folder>/.ok` and `<folder>/.ok/templates`, not just the folder —
+ // `assertNoSymlinkEscape` returns as soon as its argument realpaths
+ // in-root and never inspects components below it, so asserting the folder
+ // alone admits a planted `<folder>/.ok -> /outside` link. Anchoring on
+ // `.ok` subsumes the folder (the ENOENT walk passes through it), and both
+ // deeper asserts are free when the dirs don't exist yet.
+ // Reserved-prefix folders (`.ok`, `.git`, `.ok/skills/<name>`) are
+ // deliberately admitted here, unlike the file-ops family: the writers
+ // append the `.ok/{frontmatter.yml,templates/<pinned-name>.md}` leaf
+ // themselves, so nothing load-bearing is reachable through them.
+ try {
+ const okDir = resolve(candidateAbs, '.ok');
+ assertNoSymlinkEscape(okDir, resolvedContentDir);
+ assertNoSymlinkEscape(resolve(okDir, 'templates'), resolvedContentDir);
+ } catch (err) {
+ if (isContainmentRejection(err)) {
+ errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escapes content directory.', {
+ handler,
+ cause: err,
+ });
+ return null;
+ }
+ // Raw realpath errno or a missing content root: a server fault, not the
+ // caller's path — same split as every other containment consumer.
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to validate path.', {
handler,
+ cause: err,
});
return null;
}
@@ -19304,7 +17767,7 @@ export function createApiExtension(
{ handler: 'lint-fix' },
);
} catch (e) {
- if (e instanceof SymlinkEscapeError) {
+ if (isContainmentRejection(e)) {
errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {
handler: 'lint-fix',
});
@@ -19382,13 +17845,6 @@ export function createApiExtension(
'/api/lint/markdownlint-config': handleWriteMarkdownlintRule,
'/api/lint/frontmatter-schema': handleWriteFrontmatterSchema,
'/api/lint/fix': handleLintFix,
- '/api/create-page': handleCreatePage,
- '/api/create-folder': handleCreateFolder,
- '/api/duplicate-path': handleDuplicatePath,
- '/api/rename-path': handleRenamePath,
- '/api/delete-path': handleDeletePath,
- '/api/trash/cleanup': handleTrashCleanup,
- '/api/upload': handleUploadAsset,
'/api/agent-write': handleAgentWrite,
'/api/agent-write-md': handleAgentWriteMd,
'/api/agent-write-batch': handleAgentWriteBatch,
@@ -19445,16 +17901,9 @@ export function createApiExtension(
const MUTATING_ROUTES: ReadonlySet<string> = new Set([
'/api/comments',
'/api/comment',
- '/api/upload',
'/api/lint/markdownlint-config',
'/api/lint/frontmatter-schema',
'/api/lint/fix',
- '/api/create-page',
- '/api/create-folder',
- '/api/duplicate-path',
- '/api/rename-path',
- '/api/delete-path',
- '/api/trash/cleanup',
'/api/agent-write',
'/api/agent-write-md',
'/api/agent-write-batch',
@@ -19626,6 +18075,33 @@ export function createApiExtension(
getGeneratedIndexSettingsStatus,
setGeneratedIndexEnabled,
});
+ const fileOpsRoutes = createFileOpsRoutes({
+ contentDir,
+ projectDir,
+ log,
+ getPrincipal,
+ contentFilter,
+ signalChannel,
+ hocuspocus,
+ getSyncEngine,
+ flushContributors,
+ fileOpsService,
+ assetService,
+ extractAgentIdentity,
+ recordDerivedDocumentBestEffort,
+ invalidateReferencedAssetsCache,
+ listManagedDocNamesUnderFolderFromDisk,
+ resolveContentEntryPath,
+ docNameForFileOperationPath,
+ withPeriod,
+ toManagedRenamePublicError,
+ attributeRenameWriteToActor,
+ renameAttributionCounter,
+ _performAssetRename,
+ _performDocumentToFileRename,
+ _performManagedRenameForDocs,
+ isValidRelativeContentPath,
+ });
const seedRoutes = createSeedRoutes({
contentDir,
checkLocalOpSecurity,
@@ -19676,6 +18152,7 @@ export function createApiExtension(
skillsReadRoutes,
skillsShRoutes,
workspaceToolsRoutes,
+ fileOpsRoutes,
seedRoutes,
systemActionsRoutes,
folderTemplateRoutes,
diff --git a/packages/server/src/api-file-ops-composition.test.ts b/packages/server/src/api-file-ops-composition.test.ts
new file mode 100644
index 000000000..e0ef09119
--- /dev/null
+++ b/packages/server/src/api-file-ops-composition.test.ts
@@ -0,0 +1,569 @@
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ symlinkSync,
+ writeFileSync,
+} from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { connect } from 'node:net';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';
+import { tmpUploadDir } from './upload-streaming.ts';
+
+/**
+ * Characterization: the natively-routed file-ops group (`create-page`,
+ * `create-folder`, `duplicate-path`, `rename-path`, `delete-path`,
+ * `trash/cleanup`, multipart `upload`) over a REAL socket through the
+ * composed `bootServer` stack: verb gating (405 + `Allow: POST` on every
+ * path), the shared admission posture on a whole-family-mutating group, and
+ * `/api/upload`'s multipart body handling — including two load-bearing
+ * behaviors:
+ *
+ * - a client that disconnects mid-multipart must not wedge the request
+ * (the `readUploadBody` `req.complete` close-guard settles the parse
+ * promise when busboy never reaches its closing boundary);
+ * - an oversized JSON body on the family's ordinary routes lands as the
+ * shared body-reader's clean 413 (`payload-too-large`), while
+ * `/api/upload` deliberately has NO equivalent byte cap — its bound is
+ * the storage layer, so the happy path streams arbitrary sizes.
+ *
+ * The wire cannot distinguish the mutating gate from the read gate (both
+ * apply the same loopback + workspace-Host checks), so the mutating
+ * DECLARATION is pinned at the table tier in `http/file-ops-routes.test.ts`;
+ * the rebound-Host pins here hold the admission outcome itself.
+ */
+
+const FAMILY_PATHS = [
+ '/api/create-page',
+ '/api/create-folder',
+ '/api/duplicate-path',
+ '/api/rename-path',
+ '/api/delete-path',
+ '/api/trash/cleanup',
+ '/api/upload',
+];
+
+let tmpRoot: string;
+let contentDir: string;
+let server: BootedServer;
+
+async function postJson(path: string, body: unknown): Promise<Response> {
+ return fetch(`http://127.0.0.1:${server.port}${path}`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(body),
+ });
+}
+
+function uploadForm(fields: Record<string, string>, file?: { name: string; bytes: string }) {
+ const form = new FormData();
+ for (const [k, v] of Object.entries(fields)) form.append(k, v);
+ if (file) form.append('file', new Blob([file.bytes]), file.name);
+ return form;
+}
+
+beforeAll(async () => {
+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-file-ops-native-'));
+ contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));
+ writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');
+ server = await bootCompositionRig(contentDir);
+ await server.ready;
+}, 60_000);
+
+afterAll(async () => {
+ await server?.destroy();
+ await rm(tmpRoot, { recursive: true, force: true });
+});
+
+describe('file-ops group over the composed listener — served natively', () => {
+ test('every path is registered natively with verb gating (405 + Allow: POST)', async () => {
+ for (const path of FAMILY_PATHS) {
+ 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');
+ }
+ });
+
+ test('create-page serves natively and returns the created docName', async () => {
+ const res = await postJson('/api/create-page', { path: 'notes/created-native.md' });
+ expect(res.status).toBe(200);
+ expect(res.headers.get('x-request-id')).not.toBeNull();
+ expect(((await res.json()) as { docName?: string }).docName).toBe('notes/created-native');
+ });
+
+ test('create-page path validation still lands as typed problems', async () => {
+ const noExt = await postJson('/api/create-page', { path: 'not-a-doc.txt' });
+ expect(noExt.status).toBe(400);
+ expect(((await noExt.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');
+
+ const escaped = await postJson('/api/create-page', { path: '../outside.md' });
+ expect(escaped.status).toBe(400);
+ expect(((await escaped.json()) as { type?: string }).type).toBe('urn:ok:error:path-escape');
+ });
+
+ test('create-page rejects non-canonical `.`/empty segments (intentional tightening)', async () => {
+ // Routing containment through `resolveContentEntryPath` (vs the old
+ // `path.resolve` + prefix pair) tightened create-page to reject a `.`
+ // segment or an empty (`//`) segment, which `path.resolve` used to
+ // normalize away. This is the safer default and matches the sibling
+ // routes; pin it so the behavior is deliberate rather than incidental.
+ for (const path of ['./notes/x.md', 'notes//x.md']) {
+ const res = await postJson('/api/create-page', { path });
+ expect(res.status, path).toBe(400);
+ expect(((await res.json()) as { type?: string }).type, path).toBe('urn:ok:error:path-escape');
+ }
+ });
+
+ test('create-page refuses a path routed through a symlinked directory escaping the content root', async () => {
+ // The lexical checks pass ('sneaky/escaped.md' contains no '..'), so only
+ // the realpath symlink-escape refusal inside `resolveContentEntryPath`
+ // stands between this request and a write outside the content root.
+ const outside = mkdtempSync(resolve(tmpRoot, 'outside-'));
+ symlinkSync(outside, resolve(contentDir, 'sneaky'), 'dir');
+ const res = await postJson('/api/create-page', { path: 'sneaky/escaped.md' });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:path-escape');
+ expect(existsSync(resolve(outside, 'escaped.md'))).toBe(false);
+ });
+
+ test('create-page drops a template symlinked outside the content root from the menu', async () => {
+ // `.ok/templates/*.md` are enumerated via `statSync` (follows links), so a
+ // template symlinked to a file outside the content root would otherwise
+ // inline that file's bytes into the new doc. Containment lives in the
+ // resolver (`collectFromFolder`), so the escaping entry never enters the
+ // menu — the template simply does not resolve, and create-page returns the
+ // ordinary "does not resolve" 400 rather than reading the foreign file. The
+ // fixture is scoped under `leaky/` so the shared root template menu that
+ // every other test in this rig sees stays clean.
+ const secretDir = mkdtempSync(resolve(tmpRoot, 'secret-'));
+ writeFileSync(resolve(secretDir, 'secret.txt'), 'TOP SECRET', 'utf-8');
+ const tplDir = resolve(contentDir, 'leaky', '.ok', 'templates');
+ mkdirSync(tplDir, { recursive: true });
+ symlinkSync(resolve(secretDir, 'secret.txt'), resolve(tplDir, 'leak.md'), 'file');
+ const res = await postJson('/api/create-page', {
+ path: 'leaky/from-leak.md',
+ template: 'leak',
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');
+ expect(existsSync(resolve(contentDir, 'leaky', 'from-leak.md'))).toBe(false);
+ });
+
+ test('create-page refuses a target routed into .ok through a symlinked directory', async () => {
+ // `resolveContentEntryPath` uses `path.resolve`, which does not follow
+ // symlinks, so `escape-hatch/skills/phantom.md` — where `escape-hatch` is a
+ // symlink to `.ok` — carries no `.ok` segment lexically and stays inside the
+ // content root (so it does NOT trip symlink-escape). The reserved-path check
+ // must run on the CANONICAL path and refuse the write into `.ok/skills`.
+ symlinkSync(resolve(contentDir, '.ok'), resolve(contentDir, 'escape-hatch'), 'dir');
+ const res = await postJson('/api/create-page', {
+ path: 'escape-hatch/skills/phantom.md',
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:reserved-doc-name');
+ expect(existsSync(resolve(contentDir, '.ok', 'skills', 'phantom.md'))).toBe(false);
+ });
+
+ // The canonical reserved-path guard is shared across every mutating file-op,
+ // not just create-page: a symlinked directory that routes a lexically-clean
+ // path into `.ok`/`.git` must be refused by create-folder, duplicate-path,
+ // rename-path, and — most importantly — delete-path, whose recursive rm would
+ // otherwise resolve through the junction and destroy OK/git bookkeeping. Each
+ // case plants its own uniquely-named `.ok` symlink so the tests stay independent.
+ test('delete-path refuses a recursive delete routed into .ok through a symlink', async () => {
+ // The witness must be the exact subtree the recursive rm would destroy —
+ // `esc-del/local` resolves to `.ok/local`, so seed a file there and assert
+ // it survives (a sibling like `.ok/config.yml` would survive even a
+ // regression that follows the junction).
+ mkdirSync(resolve(contentDir, '.ok', 'local'), { recursive: true });
+ writeFileSync(resolve(contentDir, '.ok', 'local', 'survivor-marker'), 'still here', 'utf-8');
+ symlinkSync(resolve(contentDir, '.ok'), resolve(contentDir, 'esc-del'), 'dir');
+ const res = await postJson('/api/delete-path', { kind: 'folder', path: 'esc-del/local' });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:reserved-doc-name');
+ expect(existsSync(resolve(contentDir, '.ok', 'local', 'survivor-marker'))).toBe(true);
+ });
+
+ test('rename-path refuses a destination routed into .ok/skills through a symlink', async () => {
+ symlinkSync(resolve(contentDir, '.ok'), resolve(contentDir, 'esc-ren'), 'dir');
+ const res = await postJson('/api/rename-path', {
+ kind: 'file',
+ fromPath: 'alpha',
+ toPath: 'esc-ren/skills/evil',
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:reserved-doc-name');
+ expect(existsSync(resolve(contentDir, '.ok', 'skills', 'evil.md'))).toBe(false);
+ });
+
+ test('rename-path refuses a SOURCE routed into .ok through a symlink', async () => {
+ // The mirror of the destination case with its own damage profile: renaming
+ // FROM `esc-ren-src/local` would move `.ok/local` (server.lock,
+ // principal.json, cache) out of `.ok` into the synced content tree.
+ mkdirSync(resolve(contentDir, '.ok', 'local'), { recursive: true });
+ symlinkSync(resolve(contentDir, '.ok'), resolve(contentDir, 'esc-ren-src'), 'dir');
+ const res = await postJson('/api/rename-path', {
+ kind: 'folder',
+ fromPath: 'esc-ren-src/local',
+ toPath: 'stolen',
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:reserved-doc-name');
+ expect(existsSync(resolve(contentDir, '.ok', 'local'))).toBe(true);
+ expect(existsSync(resolve(contentDir, 'stolen'))).toBe(false);
+ });
+
+ test('create-folder refuses a directory routed into .ok through a symlink', async () => {
+ symlinkSync(resolve(contentDir, '.ok'), resolve(contentDir, 'esc-cf'), 'dir');
+ const res = await postJson('/api/create-folder', { path: 'esc-cf/skills' });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:reserved-doc-name');
+ });
+
+ test('duplicate-path refuses a source routed into .ok through a symlink', async () => {
+ symlinkSync(resolve(contentDir, '.ok'), resolve(contentDir, 'esc-dup'), 'dir');
+ const res = await postJson('/api/duplicate-path', { kind: 'folder', path: 'esc-dup/local' });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:reserved-doc-name');
+ });
+
+ test('upload refuses a parentDocName inside .ok, no symlink needed', async () => {
+ // `.ok` sits INSIDE the content root, so the upload path's escape checks
+ // (`..`/`/`/NUL lexically, symlink-escape in storeUpload) all pass for a
+ // literal `.ok/...` parent — the reserved-subtree gate is the only refusal.
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/upload`, {
+ method: 'POST',
+ body: uploadForm(
+ { parentDocName: '.ok/skills/planted' },
+ { name: 'evil.md', bytes: 'planted skill content' },
+ ),
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:reserved-doc-name');
+ expect(existsSync(resolve(contentDir, '.ok', 'skills', 'evil.md'))).toBe(false);
+ });
+
+ test('upload refuses a parentDocName routed into .ok through a symlink', async () => {
+ // `esc-upload/skills` carries no reserved segment lexically, so
+ // `isReservedProjectStatePath` alone would admit it — only realpath-based
+ // canonicalization sees the planted directory link. This pins the UNION of
+ // the two canonical gates (the route's fast fail and `storeUpload`'s
+ // destination-side check): deleting either alone keeps this green because
+ // the other still refuses; deleting both goes red.
+ symlinkSync(resolve(contentDir, '.ok'), resolve(contentDir, 'esc-upload'), 'dir');
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/upload`, {
+ method: 'POST',
+ body: uploadForm(
+ { parentDocName: 'esc-upload/skills/planted' },
+ { name: 'sneaky.md', bytes: 'planted skill content' },
+ ),
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:reserved-doc-name');
+ expect(existsSync(resolve(contentDir, '.ok', 'skills', 'sneaky.md'))).toBe(false);
+ });
+
+ test('upload refuses a ./-prefixed parentDocName with the same precondition as its siblings', async () => {
+ // A `.` segment defeats BOTH reserved disjuncts (`isReservedProjectStatePath`
+ // splits to ['.','esc',...]; `canonicalTargetIsReserved` swallows the
+ // resolution throw), so the gate is only sound when `isValidRelativeContentPath`
+ // runs first on the directory component — this pins that precondition.
+ // Self-contained: no planted symlink is needed, the `.` segment alone must refuse.
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/upload`, {
+ method: 'POST',
+ body: uploadForm(
+ { parentDocName: './dotted-esc/skills/planted' },
+ { name: 'dotted.md', bytes: 'planted skill content' },
+ ),
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:path-escape');
+ expect(existsSync(resolve(contentDir, 'dotted-esc'))).toBe(false);
+ });
+
+ test('upload accepts a parentDocName whose basename carries a backslash', async () => {
+ // The precondition validates only the DIRECTORY component: the basename is
+ // a raw OS filename on the sidebar external-file-drop path (the client
+ // splices `file.name` verbatim), and backslash is a legal filename
+ // character on macOS/Linux. The server discards the basename — only
+ // `dirname(parentDocName)` reaches `resolveUploadDestDir` — so this must
+ // upload, not 400.
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/upload`, {
+ method: 'POST',
+ body: uploadForm(
+ { parentDocName: 'alpha/notes\\draft.png' },
+ { name: 'dropped.png', bytes: 'png-ish bytes' },
+ ),
+ });
+ expect(res.status).toBe(200);
+ });
+
+ test('create-folder maps a symlink escape OUT of the content root to a 400, not a 500', async () => {
+ // `escape-out/foo` passes the lexical check; the service's
+ // `resolveContentEntryPath` then throws the containment rejection. The
+ // route must classify that as the caller's 400 path-escape (matching
+ // create-page and rename-path), never the generic 500 that would tag the
+ // infra-error dashboard for a client mistake.
+ const outsideTarget = mkdtempSync(resolve(tmpRoot, 'escape-out-'));
+ symlinkSync(outsideTarget, resolve(contentDir, 'escape-out'), 'dir');
+ const res = await postJson('/api/create-folder', { path: 'escape-out/foo' });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:path-escape');
+ });
+
+ test('duplicate-path maps a symlink escape OUT of the content root to a 400, not a 500', async () => {
+ // Same shape as the create-folder case above: the escape clears the lexical
+ // check, the reserved gate swallows, and the service's resolution throws the
+ // containment rejection — duplicate-path's own `isContainmentRejection` arm
+ // must classify it as the caller's 400.
+ const outsideTarget = mkdtempSync(resolve(tmpRoot, 'escape-dup-out-'));
+ symlinkSync(outsideTarget, resolve(contentDir, 'escape-dup-out'), 'dir');
+ const res = await postJson('/api/duplicate-path', {
+ kind: 'folder',
+ path: 'escape-dup-out/foo',
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:path-escape');
+ });
+
+ test('create-folder creates and refuses reserved directories', async () => {
+ const ok = await postJson('/api/create-folder', { path: 'made-native' });
+ expect(ok.status).toBe(200);
+ expect(((await ok.json()) as { path?: string }).path).toBe('made-native');
+
+ const reserved = await postJson('/api/create-folder', { path: '.ok/nested' });
+ expect(reserved.status).toBe(400);
+ expect(((await reserved.json()) as { type?: string }).type).toBe(
+ 'urn:ok:error:reserved-doc-name',
+ );
+ });
+
+ test('duplicate-path duplicates a document through the lifted route', async () => {
+ const res = await postJson('/api/duplicate-path', { kind: 'file', path: 'alpha.md' });
+ expect(res.status).toBe(200);
+ const body = (await res.json()) as { duplicatedDocNames?: string[] };
+ expect(body.duplicatedDocNames).toHaveLength(1);
+ });
+
+ test('rename-path no-op (fromPath === toPath) short-circuits to the empty success shape', async () => {
+ const res = await postJson('/api/rename-path', {
+ kind: 'file',
+ fromPath: 'alpha',
+ toPath: 'alpha',
+ });
+ expect(res.status).toBe(200);
+ expect(await res.json()).toEqual({ renamed: [], renamedAssets: [], rewrittenDocs: [] });
+ });
+
+ test('rename-path refuses reserved directories with the typed problem', async () => {
+ const res = await postJson('/api/rename-path', {
+ kind: 'file',
+ fromPath: 'alpha',
+ toPath: '.ok/alpha',
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:reserved-doc-name');
+ });
+
+ test('delete-path 404s a missing target and deletes a real one', async () => {
+ const missing = await postJson('/api/delete-path', { kind: 'file', path: 'no-such-doc' });
+ expect(missing.status).toBe(404);
+ expect(((await missing.json()) as { type?: string }).type).toBe('urn:ok:error:doc-not-found');
+
+ const seed = await postJson('/api/create-page', { path: 'doomed-native.md' });
+ expect(seed.status).toBe(200);
+ const res = await postJson('/api/delete-path', { kind: 'file', path: 'doomed-native' });
+ expect(res.status).toBe(200);
+ expect(((await res.json()) as { deletedDocNames?: string[] }).deletedDocNames).toContain(
+ 'doomed-native',
+ );
+ });
+
+ test('trash-cleanup is idempotent for an already-gone file and refuses synthetic names', async () => {
+ const gone = await postJson('/api/trash/cleanup', { kind: 'file', path: 'never-existed.md' });
+ expect(gone.status).toBe(200);
+ expect(((await gone.json()) as { deletedDocNames?: string[] }).deletedDocNames).toEqual([]);
+
+ const reserved = await postJson('/api/trash/cleanup', {
+ kind: 'folder',
+ path: '__system__',
+ });
+ expect(reserved.status).toBe(400);
+ expect(((await reserved.json()) as { type?: string }).type).toBe(
+ 'urn:ok:error:reserved-doc-name',
+ );
+ });
+
+ test('upload stores a multipart file', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/upload`, {
+ method: 'POST',
+ body: uploadForm({ parentDocName: 'alpha' }, { name: 'pic.png', bytes: 'pic-bytes-1' }),
+ });
+ expect(res.status).toBe(200);
+ const body = (await res.json()) as { src?: string; path?: string; deduped?: boolean };
+ expect(typeof body.src).toBe('string');
+ expect(typeof body.path).toBe('string');
+ expect(body.deduped).toBe(false);
+ });
+
+ test('fields-only multipart (no file part) lands as 400 no-file-received, not a hang', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/upload`, {
+ method: 'POST',
+ body: uploadForm({ parentDocName: 'alpha' }),
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:no-file-received');
+ });
+
+ test('a multipart content-type without a boundary is a 400 malformed-upload', async () => {
+ const res = await rawRequest(server.port, '/api/upload', {
+ method: 'POST',
+ headers: { 'Content-Type': 'multipart/form-data' },
+ body: 'not a multipart body',
+ });
+ expect(res.status).toBe(400);
+ expect(parseProblem(res.body).type).toBe('urn:ok:error:malformed-upload');
+ });
+
+ test('a client that disconnects mid-multipart does not wedge the server (req.complete guard)', async () => {
+ // Open a raw socket, start a multipart body whose file part never reaches
+ // the closing boundary, and drop the connection. busboy never reaches
+ // `_final`, so only readUploadBody's `req.on('close')` + `!req.complete`
+ // guard settles the parse promise. The guard's cleanup is the observable:
+ // `fail()` unlinks the minted tempfile, so the staging dir drains back to
+ // empty after each abort — without the guard the parse promise hangs and
+ // the orphan stays (the trailing healthy upload would succeed either way,
+ // so it alone cannot pin the guard). Note this pins the `req.complete`
+ // CLOSE-guard, not the `writeStream.destroy()` fd hygiene: `unlink` drops
+ // the directory entry regardless of open fds, so the drain assertion goes
+ // red only if `fail()` never runs at all.
+ const stagingDir = tmpUploadDir(contentDir);
+ const stagedUploads = () =>
+ existsSync(stagingDir)
+ ? readdirSync(stagingDir).filter((name) => name.startsWith('upload-'))
+ : [];
+ // Deadline sized so `6 × deadline` (three iterations × two waits) stays well
+ // under this test's explicit 45s budget — a genuinely stuck poll fires its
+ // own named diagnostic before vitest's generic timeout can mask which wait
+ // hung. The drain is sub-second when healthy.
+ const waitFor = async (what: string, predicate: () => boolean): Promise<void> => {
+ const deadline = Date.now() + 4_000;
+ while (!predicate()) {
+ if (Date.now() > deadline) throw new Error(`timed out waiting for ${what}`);
+ await new Promise((r) => setTimeout(r, 10));
+ }
+ };
+ const boundary = 'x-ok-test-boundary';
+ for (let i = 0; i < 3; i++) {
+ await new Promise<void>((resolveAbort, rejectAbort) => {
+ const sock = connect(server.port, '127.0.0.1', () => {
+ const partial = [
+ `POST /api/upload HTTP/1.1`,
+ `Host: 127.0.0.1:${server.port}`,
+ `Content-Type: multipart/form-data; boundary=${boundary}`,
+ `Content-Length: 100000`,
+ '',
+ `--${boundary}`,
+ `Content-Disposition: form-data; name="file"; filename="cut.bin"`,
+ `Content-Type: application/octet-stream`,
+ '',
+ 'partial-bytes-then-gone',
+ ].join('\r\n');
+ sock.write(partial);
+ // Abort only once the server has demonstrably dispatched into the
+ // write pipeline (a staged tempfile appeared) — a fixed-delay abort
+ // could beat dispatch on a loaded runner and silently degrade the
+ // whole loop to no-ops.
+ waitFor('a staged tempfile', () => stagedUploads().length > 0).then(() => {
+ sock.destroy();
+ resolveAbort();
+ }, rejectAbort);
+ });
+ sock.on('error', () => {
+ // Expected teardown noise from the destroyed socket.
+ });
+ });
+ await waitFor('the staging dir to drain', () => stagedUploads().length === 0);
+ }
+ const after = await fetch(`http://127.0.0.1:${server.port}/api/upload`, {
+ method: 'POST',
+ body: uploadForm(
+ { parentDocName: 'alpha' },
+ { name: 'after-aborts.png', bytes: 'after-abort-bytes' },
+ ),
+ });
+ expect(after.status).toBe(200);
+ }, 45_000);
+
+ test('an oversized JSON body on an ordinary family route is a clean 413', async () => {
+ const res = await rawRequest(server.port, '/api/create-page', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ path: 'big.md', pad: 'x'.repeat(1_100_000) }),
+ });
+ expect(res.status).toBe(413);
+ expect(parseProblem(res.body).type).toBe('urn:ok:error:payload-too-large');
+ });
+
+ test('the whole family refuses a rebound Host on its GET arms too (admission unchanged)', async () => {
+ for (const path of FAMILY_PATHS) {
+ const res = await rawRequest(server.port, path, {
+ headers: { Host: 'evil.example' },
+ });
+ expect(res.status, path).toBe(403);
+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:host-not-allowed');
+ // Gate-before-405: the refusal happens before verb dispatch, so no
+ // Allow header leaks from the method router.
+ expect(res.headers.allow, path).toBeUndefined();
+ }
+ });
+
+ test('foreign Origin is refused before dispatch on a ported route', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/upload`, {
+ method: 'POST',
+ headers: { Origin: 'https://evil.example' },
+ body: uploadForm(
+ { parentDocName: 'alpha' },
+ { name: 'x.png', bytes: 'origin-refused-bytes' },
+ ),
+ });
+ expect(res.status).toBe(403);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-origin');
+ });
+
+ test('any forwarding header trips the proxied-request refusal on a ported route', async () => {
+ const res = await rawRequest(server.port, '/api/delete-path', {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ 'X-Forwarded-For': '203.0.113.7',
+ },
+ body: JSON.stringify({ kind: 'file', path: 'alpha' }),
+ });
+ 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('OPTIONS preflight answers 204 on a ported route', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/upload`, {
+ method: 'OPTIONS',
+ headers: { Origin: 'http://localhost:5173' },
+ });
+ expect(res.status).toBe(204);
+ expect(res.headers.get('access-control-allow-methods')).toBe('GET, POST, PUT, DELETE, OPTIONS');
+ });
+
+ test('both chained groups answer on one server (multi-group dispatch)', async () => {
+ const linkGraph = await fetch(`http://127.0.0.1:${server.port}/api/backlinks?docName=alpha`);
+ expect(linkGraph.status).toBe(200);
+ const created = await postJson('/api/create-page', { path: 'chained-dispatch.md' });
+ expect(created.status).toBe(200);
+ });
+});
diff --git a/packages/server/src/api-file-ops.test.ts b/packages/server/src/api-file-ops.test.ts
index 432ce24b7..26614fdc8 100644
--- a/packages/server/src/api-file-ops.test.ts
+++ b/packages/server/src/api-file-ops.test.ts
@@ -3042,7 +3042,11 @@ describe('file operation API routes', () => {
path: 'evil/victim',
});
- expect(result.status).toBe(500);
+ // A symlink escape is a client-shaped rejection, not a server fault: the
+ // containment family maps to a 400 path-escape. The victim outside the
+ // content root must survive either way.
+ expect(result.status).toBe(400);
+ expect((JSON.parse(result.body) as { type?: string }).type).toBe('urn:ok:error:path-escape');
expect(existsSync(victim)).toBe(true);
},
);
diff --git a/packages/server/src/api-folder-config.test.ts b/packages/server/src/api-folder-config.test.ts
index 9ed04c89b..06b217fad 100644
--- a/packages/server/src/api-folder-config.test.ts
+++ b/packages/server/src/api-folder-config.test.ts
@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import { readFile } from 'node:fs/promises';
import type { IncomingMessage, ServerResponse } from 'node:http';
import { tmpdir } from 'node:os';
@@ -156,6 +156,58 @@ describe('GET/PUT /api/folder-config', () => {
expect(absolute.status).toBe(400);
});
+ test('PUT refuses a folder that symlinks out of the content root', async () => {
+ // The lexical prefix gate cannot see this shape: `escape/x` resolves under
+ // the content dir as a string while the directory link routes the write to
+ // `/outside/x/.ok/frontmatter.yml`. The canonical containment arm in
+ // `validateFolderRel` is what refuses it.
+ const outside = join(tmpDir, 'outside');
+ mkdirSync(outside);
+ symlinkSync(outside, join(contentDir, 'escape'), 'dir');
+ const ext = buildExt();
+ const captured = await dispatch(ext, '/api/folder-config', 'PUT', {
+ path: 'escape/x',
+ frontmatter: { status: 'draft' },
+ });
+ expect(captured.status).toBe(400);
+ expect(JSON.parse(captured.body).type).toBe('urn:ok:error:path-escape');
+ expect(existsSync(join(outside, 'x', '.ok', 'frontmatter.yml'))).toBe(false);
+ });
+
+ test('PUT refuses a REAL folder whose .ok is a symlink out of the content root', async () => {
+ // The spelling the folder-anchored gate missed: the folder itself realpaths
+ // in-root, and the planted link sits one component deeper, exactly where
+ // the writer targets. The gate must anchor on `<folder>/.ok`, not the
+ // folder — `assertNoSymlinkEscape` never inspects components below its
+ // argument.
+ const outside = join(tmpDir, 'outside-okdir');
+ mkdirSync(outside);
+ mkdirSync(join(contentDir, 'notes-real'));
+ symlinkSync(outside, join(contentDir, 'notes-real', '.ok'), 'dir');
+ const ext = buildExt();
+ const captured = await dispatch(ext, '/api/folder-config', 'PUT', {
+ path: 'notes-real',
+ frontmatter: { status: 'draft' },
+ });
+ expect(captured.status).toBe(400);
+ expect(JSON.parse(captured.body).type).toBe('urn:ok:error:path-escape');
+ expect(existsSync(join(outside, 'frontmatter.yml'))).toBe(false);
+ });
+
+ test('PUT surfaces a missing content root as a 500, not a 400', async () => {
+ // The 400 arm refuses the caller's path; a vanished content root is the
+ // SERVER's fault and must not land in the path-escape bucket — the split
+ // is the substance of the containment taxonomy, so it gets its own pin.
+ const ext = buildExt();
+ rmSync(contentDir, { recursive: true, force: true });
+ const captured = await dispatch(ext, '/api/folder-config', 'PUT', {
+ path: 'plain',
+ frontmatter: { status: 'draft' },
+ });
+ expect(captured.status).toBe(500);
+ expect(JSON.parse(captured.body).type).toBe('urn:ok:error:internal-server-error');
+ });
+
test('PUT writes the sidecar and reports written, then noop on an identical patch', async () => {
const ext = buildExt();
const first = await dispatch(ext, '/api/folder-config', 'PUT', {
diff --git a/packages/server/src/api-folder-template-composition.test.ts b/packages/server/src/api-folder-template-composition.test.ts
index a0afebdaf..f24a1e1ce 100644
--- a/packages/server/src/api-folder-template-composition.test.ts
+++ b/packages/server/src/api-folder-template-composition.test.ts
@@ -1,4 +1,4 @@
-import { mkdtempSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
@@ -32,11 +32,12 @@ const METHOD_SURFACE: ReadonlyArray<{ path: string; unsupported: string; allow:
const ALL_ROUTES = METHOD_SURFACE.map(({ path }) => path);
let tmpRoot: string;
+let contentDir: string;
let server: BootedServer;
beforeAll(async () => {
tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-folder-template-native-'));
- const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));
+ contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));
writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');
server = await bootCompositionRig(contentDir);
await server.ready;
@@ -87,6 +88,50 @@ describe('folder-template group over the composed listener — served natively',
expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');
});
+ test('PUT /api/template refuses a folder that symlinks out of the content root', async () => {
+ // The reader half of the templates feature drops symlinked entries from
+ // the menu; this pins the WRITER half to the same boundary — the lexical
+ // folder gate alone would let a `tpl-escape -> /outside` directory link
+ // land `.ok/templates/<name>.md` outside the root.
+ const outside = await mkdtemp(resolve(tmpRoot, 'tpl-outside-'));
+ symlinkSync(outside, resolve(contentDir, 'tpl-escape'), 'dir');
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/template`, {
+ method: 'PUT',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ folder: 'tpl-escape/sub',
+ name: 'planted',
+ body: 'body',
+ frontmatter: { title: 'Planted' },
+ }),
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:path-escape');
+ expect(existsSync(resolve(outside, 'sub', '.ok', 'templates', 'planted.md'))).toBe(false);
+ });
+
+ test('PUT /api/template refuses a real .ok whose templates dir symlinks out', async () => {
+ // Pins the second anchor specifically: the folder AND its `.ok` are real
+ // in-root directories; only `.ok/templates` is the planted link. The
+ // `okDir` assert passes, so only the `okDir/templates` assert refuses.
+ const outside = await mkdtemp(resolve(tmpRoot, 'tpl-outside-deep-'));
+ mkdirSync(resolve(contentDir, 'tpl-real', '.ok'), { recursive: true });
+ symlinkSync(outside, resolve(contentDir, 'tpl-real', '.ok', 'templates'), 'dir');
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/template`, {
+ method: 'PUT',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ folder: 'tpl-real',
+ name: 'planted',
+ body: 'body',
+ frontmatter: { title: 'Planted' },
+ }),
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:path-escape');
+ expect(existsSync(resolve(outside, 'planted.md'))).toBe(false);
+ });
+
test('template/import refuses a schema-invalid body with 400 before any doc read', async () => {
const res = await fetch(`http://127.0.0.1:${server.port}/api/template/import`, {
method: 'POST',
diff --git a/packages/server/src/apply-managed-rename.ts b/packages/server/src/apply-managed-rename.ts
index d72cf420f..d15ce4841 100644
--- a/packages/server/src/apply-managed-rename.ts
+++ b/packages/server/src/apply-managed-rename.ts
@@ -107,17 +107,10 @@ export class ManagedRenameReservedPathError extends Error {
}
}
-/**
- * Thrown when a `safeContentPath` resolution lands outside the content
- * directory — content dir missing, path resolves outside, or a symlink cycle.
- * Caller surfaces as 400 `urn:ok:error:path-escape`.
- */
-export class SymlinkEscapeError extends Error {
- constructor(message: string) {
- super(`symlink-escape: ${message}`);
- this.name = 'SymlinkEscapeError';
- }
-}
+// Re-exported for the historical import path; the containment error family
+// (SymlinkEscapeError, PathContainmentError, isContainmentRejection) lives
+// with the check that throws it in fs-safety.ts.
+export { SymlinkEscapeError } from './fs-safety.ts';
/**
* Thrown when managed rename starts before the backlink index has been
diff --git a/packages/server/src/content/managed-doc-enum.ts b/packages/server/src/content/managed-doc-enum.ts
index 42ed4a244..9ebac9a1d 100644
--- a/packages/server/src/content/managed-doc-enum.ts
+++ b/packages/server/src/content/managed-doc-enum.ts
@@ -12,7 +12,14 @@ import { errnoCode } from '../http/handler-utils.ts';
* by the FileOps service and the managed-rename spine; do not fork it.
*/
-/** True when any path segment is OK state (`.ok/`) or git internals. */
+/**
+ * True when any `/`-separated segment of `path` is `.ok` or `.git`, at any
+ * depth — nested `<folder>/.ok/` is a first-class OK shape (folder metadata +
+ * templates), so a top-level-only check is not a boundary. Segments compare
+ * case-insensitively: on the default case-insensitive macOS filesystem an
+ * externally-addressed `.OK/x` IS `.ok/x`. Same segment walk as
+ * `pathHasAlwaysSkipSegment` in content-filter.ts.
+ */
export function isReservedProjectStatePath(path: string): boolean {
return path.split('/').some((segment) => {
const normalized = segment.toLowerCase();
diff --git a/packages/server/src/content/templates-resolver.test.ts b/packages/server/src/content/templates-resolver.test.ts
index 290919952..c5cab32ab 100644
--- a/packages/server/src/content/templates-resolver.test.ts
+++ b/packages/server/src/content/templates-resolver.test.ts
@@ -217,6 +217,76 @@ describe('resolveTemplatesAvailable', () => {
expect(tpls[0]?.title).toBeUndefined();
expect(tpls[0]?.description).toBeUndefined();
});
+
+ test('a template symlinked outside the project root is dropped from the menu', async () => {
+ // `statSync` follows the link, so an escaping template would otherwise
+ // surface as a menu entry every consumer trusts to read. Containment is
+ // enforced here in the resolver, so it never appears. A sibling legitimate
+ // template in the same folder still resolves.
+ const outside = await mkdtemp(join(tmpdir(), 'tpl-outside-'));
+ try {
+ writeFileSync(join(outside, 'secret.txt'), 'TOP SECRET');
+ writeTemplate('notes', 'ok', withFm('OK', 'In-root template.'));
+ const tplDir = join(projectDir, 'notes', '.ok', 'templates');
+ symlinkSync(join(outside, 'secret.txt'), join(tplDir, 'leak.md'), 'file');
+
+ const tpls = resolveTemplatesAvailable(projectDir, 'notes');
+ expect(tpls.map((t) => t.name).sort()).toEqual(['ok']);
+ } finally {
+ await rm(outside, { recursive: true, force: true });
+ }
+ });
+
+ test('a template symlinked to an in-root but out-of-templates path is dropped', () => {
+ // The containment anchor is the enumerating `.ok/templates/` directory, not
+ // the project root. A link pointing INSIDE the root but at `.ok/local/`
+ // (agent scratch, out of content scope) would still exfiltrate that file's
+ // bytes into a newly created doc, so it must drop too — a project-root anchor
+ // would have kept it.
+ const okLocal = join(projectDir, '.ok', 'local');
+ mkdirSync(okLocal, { recursive: true });
+ writeFileSync(join(okLocal, 'last-spawn-error.log'), 'stack trace with secrets');
+ writeTemplate('notes', 'ok', withFm('OK', 'In-root template.'));
+ symlinkSync(
+ join(okLocal, 'last-spawn-error.log'),
+ join(projectDir, 'notes', '.ok', 'templates', 'leak.md'),
+ 'file',
+ );
+
+ const tpls = resolveTemplatesAvailable(projectDir, 'notes');
+ expect(tpls.map((t) => t.name).sort()).toEqual(['ok']);
+ });
+
+ test('a templates DIRECTORY symlinked out of the project drops all its entries', async () => {
+ // A symlinked `.ok/templates` is refused wholesale by the `lstat` gate
+ // (and, as backstop, `assertNoSymlinkEscape` realpaths its ANCHOR, so a
+ // `templatesDir`-only anchor would relocate to the link target — the
+ // project-root anchor refuses the out-of-project shape even without the
+ // gate). This pins the out-of-project direction.
+ const outside = await mkdtemp(join(tmpdir(), 'tpl-dir-outside-'));
+ try {
+ writeFileSync(join(outside, 'leak.md'), withFm('Leak', 'Foreign template.'));
+ mkdirSync(join(projectDir, 'notes', '.ok'), { recursive: true });
+ symlinkSync(outside, join(projectDir, 'notes', '.ok', 'templates'), 'dir');
+
+ expect(resolveTemplatesAvailable(projectDir, 'notes')).toEqual([]);
+ } finally {
+ await rm(outside, { recursive: true, force: true });
+ }
+ });
+
+ test('a templates DIRECTORY symlinked elsewhere IN-project is skipped wholesale', async () => {
+ // The per-entry anchors cannot catch this shape: anchor 1 realpaths to the
+ // link target and every entry is trivially inside it; anchor 2 passes
+ // because the target is inside the project. Only the `lstat` gate — which
+ // does not follow the link — refuses it, keeping in-project `.md` files
+ // (e.g. `.okignore`-excluded ones) from surfacing as menu items.
+ writeFileSync(join(projectDir, 'stash.md'), withFm('Stash', 'Not a template.'));
+ mkdirSync(join(projectDir, 'notes', '.ok'), { recursive: true });
+ symlinkSync(projectDir, join(projectDir, 'notes', '.ok', 'templates'), 'dir');
+
+ expect(resolveTemplatesAvailable(projectDir, 'notes')).toEqual([]);
+ });
});
describe('resolveProjectTemplates', () => {
diff --git a/packages/server/src/content/templates-resolver.ts b/packages/server/src/content/templates-resolver.ts
index 03c4d38a6..51d00d330 100644
--- a/packages/server/src/content/templates-resolver.ts
+++ b/packages/server/src/content/templates-resolver.ts
@@ -25,10 +25,12 @@
* reason — see its doc comment.
*/
-import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { type Dirent, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
import { readdir, stat } from 'node:fs/promises';
import { join, posix } from 'node:path';
import { parseTemplateFile } from '@inkeep/open-knowledge-core';
+import { SymlinkEscapeError } from '../apply-managed-rename.ts';
+import { assertNoSymlinkEscape } from '../fs-safety.ts';
import { errnoCode } from '../http/handler-utils.ts';
import { getLogger } from '../logger.ts';
@@ -68,6 +70,18 @@ interface ResolveTemplatesOptions {
/**
* Resolve the templates menu for a target folder.
*
+ * Containment contract: a `.ok/templates` that is itself a symlink is skipped
+ * wholesale (`lstat` gate — the per-entry anchors constrain entries, not the
+ * directory they were enumerated from), and every entry returned resolves (via
+ * realpath) to a file inside the real `.ok/templates/` directory it was
+ * enumerated from AND inside `projectDir` — the conjunction, not either alone.
+ * `collectFromFolder` drops any `.ok/templates/*.md` that fails either anchor:
+ * the first catches a link that stays inside the project but points at
+ * `.ok/local/` or `.git/`; the second is defense-in-depth against the dir
+ * relocating between the `lstat` gate and enumeration. A menu entry is
+ * therefore always safe for a consumer to read.
+ * Shared by `resolveProjectTemplates`, so both surfaces inherit the guarantee.
+ *
* @param projectDir - Absolute project root.
* @param folderRelPath - Project-root-relative folder path. Empty / `.`
* means the project root.
@@ -263,7 +277,42 @@ function collectFromFolder(
? join(projectDir, folderRelPath, '.ok', 'templates')
: join(projectDir, '.ok', 'templates');
- if (!existsSync(templatesDir)) return;
+ // Refuse a `.ok/templates` that is not a REAL directory. `existsSync` /
+ // `readdirSync` follow a directory symlink, and the per-entry anchors below
+ // constrain each ENTRY, not the directory it was enumerated from — a
+ // templates dir symlinked elsewhere IN-project would pass both anchors
+ // (anchor 1 realpaths to the link target; anchor 2 because the target is
+ // inside the project) and surface foreign `.md` files as menu items. `lstat`
+ // does not follow the link, so a symlinked templates dir is skipped wholesale.
+ // Deliberately blanket: an in-project `-> ../../shared-templates` link is
+ // refused too — the safer default until shared templates are a first-class
+ // shape. Both refusals below warn once per path (the sibling drop paths'
+ // pattern) so a vanished menu is traceable; only the benign ENOENT
+ // ("no templates here", the overwhelmingly common case) stays silent.
+ let dirStat: ReturnType<typeof lstatSync>;
+ try {
+ dirStat = lstatSync(templatesDir);
+ } catch (err) {
+ if (errnoCode(err) !== 'ENOENT' && !templateMetaWarnedPaths.has(templatesDir)) {
+ templateMetaWarnedPaths.add(templatesDir);
+ const reason = err instanceof Error ? err.message : String(err);
+ getLogger('templates').warn(
+ { dir: templatesDir, reason },
+ `cannot stat templates directory ${templatesDir} — its templates are not enumerated. Reason: ${reason}`,
+ );
+ }
+ return;
+ }
+ if (!dirStat.isDirectory()) {
+ if (!templateMetaWarnedPaths.has(templatesDir)) {
+ templateMetaWarnedPaths.add(templatesDir);
+ getLogger('templates').warn(
+ { dir: templatesDir },
+ `${templatesDir} is not a real directory (symlink or file) — its templates are not enumerated`,
+ );
+ }
+ return;
+ }
let entries: string[];
try {
@@ -286,6 +335,60 @@ function collectFromFolder(
}
if (!s.isFile()) continue;
+ // Containment is enforced HERE so every consumer of the templates menu —
+ // create-page, the MCP write tool, `/api/templates`, the `exec` ls
+ // enrichment — inherits it from one point. `statSync` above follows
+ // symlinks, so a `<folder>/.ok/templates/<name>.md` symlink would otherwise
+ // let that consumer inline arbitrary file bytes into a new doc, or surface a
+ // foreign file's frontmatter as template metadata. TWO anchors, and both are
+ // load-bearing — they are complementary, not alternatives:
+ // - `templatesDir`: the entry must not leave the dir it was enumerated from.
+ // A link that realpaths elsewhere INSIDE the project (e.g.
+ // `-> ../local/last-spawn-error.log` or `-> ../../.git/config`) is still an
+ // exfiltration channel into the synced content tree; `.ok/local/` and
+ // `.git/` are deliberately out of content scope.
+ // - `projectDir`: `assertNoSymlinkEscape` realpaths its ANCHOR, so if
+ // `templatesDir` were itself a symlink out of the project, the first
+ // anchor would become the link target and admit everything under it. The
+ // `lstat` gate above refuses a symlinked templates dir before enumeration;
+ // this anchor is the defense-in-depth backstop for a dir replaced by a
+ // link between that gate and this check.
+ // Drop an escaping entry from the menu (a consumer can then never select it)
+ // rather than throwing: the resolver's contract is to return a menu, and such
+ // an entry simply is not a valid menu item. A raw realpath errno means the
+ // file exists but cannot be canonicalized — it cannot be read either, so it
+ // is dropped the same way.
+ try {
+ assertNoSymlinkEscape(absPath, templatesDir);
+ assertNoSymlinkEscape(absPath, projectDir);
+ } catch (err) {
+ if (err instanceof SymlinkEscapeError) {
+ if (!templateMetaWarnedPaths.has(absPath)) {
+ templateMetaWarnedPaths.add(absPath);
+ // `reason` distinguishes the two escape conditions (resolves
+ // outside / symlink cycle) — one log line per path, so the condition
+ // must ride along. A missing anchor dir throws the non-containment
+ // `ContentRootUnavailableError` and routes to the canonicalize-
+ // failure warn below instead.
+ getLogger('templates').warn(
+ { template: absPath, reason: err.message },
+ `template ${absPath} escapes its containment boundary — excluded from the menu. Reason: ${err.message}`,
+ );
+ }
+ continue;
+ }
+ const code = errnoCode(err);
+ if (code !== 'ENOENT' && !templateMetaWarnedPaths.has(absPath)) {
+ templateMetaWarnedPaths.add(absPath);
+ const reason = err instanceof Error ? err.message : String(err);
+ getLogger('templates').warn(
+ { template: absPath, reason },
+ `failed to canonicalize template ${absPath} — excluded from the menu. Reason: ${reason}`,
+ );
+ }
+ continue;
+ }
+
const meta = readTemplateMeta(absPath);
const relPath = folderRelPath
? posix.join(folderRelPath, '.ok', 'templates', entryName)
diff --git a/packages/server/src/fs-safety.test.ts b/packages/server/src/fs-safety.test.ts
new file mode 100644
index 000000000..bfa287935
--- /dev/null
+++ b/packages/server/src/fs-safety.test.ts
@@ -0,0 +1,162 @@
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, win32 } from 'node:path';
+import { describe, expect, test } from 'vitest';
+import { isReservedProjectStatePath } from './content/managed-doc-enum.ts';
+import {
+ assertNoSymlinkEscape,
+ ContentRootUnavailableError,
+ canonicalRelPathForNewTarget,
+ isContainmentRejection,
+ PathContainmentError,
+ SymlinkEscapeError,
+} from './fs-safety.ts';
+import { loggerFactory } from './logger.ts';
+
+describe('containment error family classification', () => {
+ // The classifier is the single decision every route catch keys 400-vs-500 on,
+ // so the membership itself is the contract: both containment halves are in,
+ // the missing-anchor server fault is out.
+ test('admits both containment halves and rejects everything else', () => {
+ expect(isContainmentRejection(new PathContainmentError('path must be relative'))).toBe(true);
+ expect(isContainmentRejection(new SymlinkEscapeError('path resolves outside'))).toBe(true);
+ expect(isContainmentRejection(new ContentRootUnavailableError('content dir gone'))).toBe(false);
+ expect(isContainmentRejection(new Error('EACCES: permission denied'))).toBe(false);
+ expect(isContainmentRejection(undefined)).toBe(false);
+ });
+
+ test('a missing content dir throws the non-containment ContentRootUnavailableError', () => {
+ // The anchor itself being absent is a SERVER condition (dir deleted under a
+ // running server, unmounted volume) — routes must surface it as a 500, so
+ // it must NOT classify as a containment rejection.
+ const root = mkdtempSync(join(tmpdir(), 'fs-safety-'));
+ try {
+ const missingAnchor = join(root, 'never-created');
+ let caught: unknown;
+ try {
+ assertNoSymlinkEscape(join(missingAnchor, 'doc.md'), missingAnchor);
+ } catch (e) {
+ caught = e;
+ }
+ expect(caught).toBeInstanceOf(ContentRootUnavailableError);
+ expect(isContainmentRejection(caught)).toBe(false);
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+ });
+
+ test('an out-of-root symlink throws the containment SymlinkEscapeError', () => {
+ const root = mkdtempSync(join(tmpdir(), 'fs-safety-'));
+ try {
+ const contentDir = join(root, 'content');
+ const outside = join(root, 'outside');
+ mkdirSync(contentDir);
+ mkdirSync(outside);
+ symlinkSync(outside, join(contentDir, 'esc'), 'dir');
+ let caught: unknown;
+ try {
+ assertNoSymlinkEscape(join(contentDir, 'esc', 'doc.md'), contentDir);
+ } catch (e) {
+ caught = e;
+ }
+ expect(caught).toBeInstanceOf(SymlinkEscapeError);
+ expect(isContainmentRejection(caught)).toBe(true);
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+ });
+});
+
+describe('canonicalRelPathForNewTarget', () => {
+ const log = loggerFactory.getLogger('test');
+ const errno = (code: string): NodeJS.ErrnoException => {
+ const e = new Error(`${code}: injected`) as NodeJS.ErrnoException;
+ e.code = code;
+ return e;
+ };
+
+ // The return value feeds `isReservedProjectStatePath`, which splits on `/`,
+ // so the helper's postcondition is a `/`-separated path on every platform.
+ // The POSIX tests pin the branch logic + reattachment; the win32 tests below
+ // drive the injected `win32` path flavor from this (Linux) runner, since the
+ // CI matrix has no Windows cell running this suite.
+
+ test('ascends past a missing leaf and canonicalizes through a symlinked ancestor', () => {
+ // `/c/sneaky` is a symlink to `/c/.ok`; the target file does not exist yet.
+ const realpath = ((p: string): string => {
+ if (p === '/c') return '/c';
+ if (p === '/c/sneaky') return '/c/.ok';
+ throw errno('ENOENT');
+ }) as unknown as typeof import('node:fs').realpathSync;
+ expect(canonicalRelPathForNewTarget('/c/sneaky/phantom.md', '/c', log, realpath)).toBe(
+ '.ok/phantom.md',
+ );
+ });
+
+ test('falls back to the lexical relative path on a raw realpath errno', () => {
+ const realpath = ((): string => {
+ throw errno('EACCES');
+ }) as unknown as typeof import('node:fs').realpathSync;
+ expect(canonicalRelPathForNewTarget('/c/notes/x.md', '/c', log, realpath)).toBe('notes/x.md');
+ });
+
+ test('falls back to the lexical relative path when ENOENT reaches the filesystem root', () => {
+ const realpath = ((): string => {
+ throw errno('ENOENT');
+ }) as unknown as typeof import('node:fs').realpathSync;
+ expect(canonicalRelPathForNewTarget('/c/a/b/x.md', '/c', log, realpath)).toBe('a/b/x.md');
+ });
+
+ test('win32: a symlinked-ancestor result still satisfies the /-split consumer', () => {
+ // `path.win32.relative` joins with `\`; without the toPosix normalization the
+ // consumer `isReservedProjectStatePath` (which splits on `/`) sees one opaque
+ // segment and the guard is silently inert on Windows. The second assertion is
+ // the load-bearing producer→consumer contract: it goes red the instant a
+ // `toPosix` call is dropped.
+ const realpath = ((p: string): string => {
+ if (p === 'C:\\c') return 'C:\\c';
+ if (p === 'C:\\c\\sneaky') return 'C:\\c\\.ok';
+ throw errno('ENOENT');
+ }) as unknown as typeof import('node:fs').realpathSync;
+ const out = canonicalRelPathForNewTarget('C:\\c\\sneaky\\phantom.md', 'C:\\c', log, realpath, {
+ join: win32.join,
+ relative: win32.relative,
+ dirname: win32.dirname,
+ sep: win32.sep,
+ });
+ expect(out).toBe('.ok/phantom.md');
+ expect(isReservedProjectStatePath(out)).toBe(true);
+ });
+
+ test('win32: the raw-errno lexical fallback is also /-normalized', () => {
+ const realpath = ((): string => {
+ throw errno('EACCES');
+ }) as unknown as typeof import('node:fs').realpathSync;
+ const out = canonicalRelPathForNewTarget('C:\\c\\.ok\\x.md', 'C:\\c', log, realpath, {
+ join: win32.join,
+ relative: win32.relative,
+ dirname: win32.dirname,
+ sep: win32.sep,
+ });
+ expect(out).toBe('.ok/x.md');
+ expect(isReservedProjectStatePath(out)).toBe(true);
+ });
+
+ test('win32: the ENOENT-to-filesystem-root fallback is also /-normalized', () => {
+ // The bootstrap window: nothing in the ancestor chain realpaths (content
+ // dir not created yet), so the helper falls back to the lexical relative
+ // path via the third exit. Same producer→consumer assertion as above —
+ // dropping the toPosix wrapper from that exit alone must go red here.
+ const realpath = ((): string => {
+ throw errno('ENOENT');
+ }) as unknown as typeof import('node:fs').realpathSync;
+ const out = canonicalRelPathForNewTarget('C:\\c\\.ok\\deep\\x.md', 'C:\\c', log, realpath, {
+ join: win32.join,
+ relative: win32.relative,
+ dirname: win32.dirname,
+ sep: win32.sep,
+ });
+ expect(out).toBe('.ok/deep/x.md');
+ expect(isReservedProjectStatePath(out)).toBe(true);
+ });
+});
diff --git a/packages/server/src/fs-safety.ts b/packages/server/src/fs-safety.ts
index cb5dca66d..72e18e386 100644
--- a/packages/server/src/fs-safety.ts
+++ b/packages/server/src/fs-safety.ts
@@ -1,14 +1,50 @@
import { realpathSync } from 'node:fs';
-import { dirname, sep } from 'node:path';
-import { SymlinkEscapeError } from './apply-managed-rename.ts';
+import { dirname, join, relative, sep } from 'node:path';
import { isWithinContentDir } from './content-path.ts';
+import { normalizeFsPath } from './fs-traced.ts';
import { errnoCode } from './http/handler-utils.ts';
+import type { PinoLogger } from './logger.ts';
/**
* Filesystem-safety predicates shared by every write surface that creates or
* moves entries under the content directory (uploads, file ops, renames).
+ * Home of the containment error family: `SymlinkEscapeError` (realpath half),
+ * `PathContainmentError` (lexical half), the `isContainmentRejection`
+ * classifier over both, and the non-containment `ContentRootUnavailableError`
+ * (missing anchor — a server fault, outside the family). Also home of
+ * `canonicalRelPathForNewTarget`, the canonicalizer reserved-subtree checks
+ * run on not-yet-existing targets. `apply-managed-rename.ts` re-exports
+ * `SymlinkEscapeError` for its historical import path.
*/
+/**
+ * Thrown when a `safeContentPath` resolution lands outside the content
+ * directory — path resolves outside, or a symlink cycle. Caller surfaces as
+ * 400 `urn:ok:error:path-escape`. (A missing content dir is NOT this — see
+ * `ContentRootUnavailableError` below.)
+ */
+export class SymlinkEscapeError extends Error {
+ constructor(message: string) {
+ super(`symlink-escape: ${message}`);
+ this.name = 'SymlinkEscapeError';
+ }
+}
+
+/**
+ * Thrown when the containment ANCHOR itself is missing: the content directory
+ * does not exist, so there is no baseline to check a path against. This is a
+ * server-side condition (dir deleted under a running server, unmounted volume),
+ * not a malformed request, so it is deliberately NOT part of the containment
+ * family — `isContainmentRejection` returns false and route catches let it
+ * surface as a typed 500 instead of blaming the caller with a 400 path-escape.
+ */
+export class ContentRootUnavailableError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = 'ContentRootUnavailableError';
+ }
+}
+
/**
* Ensures `fullPath` does not escape `resolvedContentDir` via symlinks (matches persistence
* symlink-escape checks). Walks up with dirname when the leaf is missing so destinations like
@@ -24,15 +60,16 @@ export function assertNoSymlinkEscape(fullPath: string, resolvedContentDir: stri
} catch (err) {
const code = errnoCode(err);
// ENOENT means the content dir hasn't been created yet — no symlink
- // escape is possible against a non-existent directory, but we have
- // no safe baseline for the check either. Throw the same
- // `symlink-escape:` error class so the caller's catch routes through
- // the existing error path. Other errno classes (EPERM, EIO, ENOMEM)
- // must NOT be swallowed silently — they'd leave the security gate
- // disabled with no log line, no telemetry, no error response. Throw
- // and let the top-level handler emit a typed RFC 9457 problem.
+ // escape is possible against a non-existent directory, but we have no
+ // safe baseline for the check either. This is the SERVER's problem, not
+ // the caller's, so it throws the non-containment
+ // `ContentRootUnavailableError` and surfaces as a 500 rather than a 400
+ // path-escape. Other errno classes (EPERM, EIO, ENOMEM) must NOT be
+ // swallowed silently — they'd leave the security gate disabled with no
+ // log line, no telemetry, no error response. Throw and let the
+ // top-level handler emit a typed RFC 9457 problem.
if (code === 'ENOENT') {
- throw new SymlinkEscapeError('content directory does not exist');
+ throw new ContentRootUnavailableError('content directory does not exist');
}
throw err;
}
@@ -71,6 +108,115 @@ export function assertNoSymlinkEscape(fullPath: string, resolvedContentDir: stri
}
}
+/**
+ * Raised by the lexical half of content-path containment — before the realpath
+ * symlink check — for a path that is absent/absolute/backslashed/NUL-bearing,
+ * carries a `.` or `..` segment, or resolves outside the content root by string
+ * prefix. Its sibling `SymlinkEscapeError` (above in this module) covers
+ * the realpath half. Both are the CALLER's fault and map to a 400 path-escape;
+ * they differ only in which check tripped. A raw realpath errno
+ * (EACCES/EIO/ESTALE) rethrown by `assertNoSymlinkEscape` is NOT one of these —
+ * it is an infrastructure fault and must surface as a 500.
+ */
+export class PathContainmentError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = 'PathContainmentError';
+ }
+}
+
+/**
+ * True when `err` is a client-side containment rejection: the lexical
+ * `PathContainmentError` or the realpath `SymlinkEscapeError`. This is exactly
+ * the set a path-resolution catch maps to a 400 path-escape — everything else
+ * (notably the raw realpath errnos `assertNoSymlinkEscape` rethrows by contract,
+ * and `ContentRootUnavailableError` for a missing content dir) must propagate so
+ * it surfaces as a typed 500 with the right log level and telemetry tag, not a
+ * misleading client 400.
+ */
+export function isContainmentRejection(err: unknown): boolean {
+ return err instanceof PathContainmentError || err instanceof SymlinkEscapeError;
+}
+
+function logCanonicalizationFault(log: PinoLogger, path: string, err: unknown): void {
+ // Keep the raw error object in the structured fields so the errno `code`
+ // survives for grepping/alerting; the message carries only the summary.
+ log.warn(
+ { path: normalizeFsPath(path), code: errnoCode(err), err },
+ '[fs-safety] reserved-path canonicalization fell back to the lexical path; a symlink-based reserved-subtree check may be stale for this request',
+ );
+}
+
+/**
+ * Canonical contentDir-relative path for a target that does not exist yet,
+ * always `/`-separated. `path.resolve` does not follow symlinks, so a lexical
+ * `fullPath` can name a reserved subtree without any `.ok`/`.git` segment (a
+ * symlinked directory). Realpath the nearest existing ancestor and re-attach the
+ * missing tail so a reserved-path check sees where the write would ACTUALLY
+ * land. The content root is realpath'd too, so a platform alias (macOS `/var` →
+ * `/private/var`) on one side doesn't skew the relative result.
+ *
+ * POSTCONDITION: the return value uses `/` separators regardless of platform.
+ * This is a contract with the sole consumer `isReservedProjectStatePath`, which
+ * does `path.split('/')` — a `\`-separated win32 result would split into one
+ * element and silently defeat the guard. TypeScript cannot express this, hence
+ * the explicit normalization at every exit.
+ *
+ * Falls back to the lexical relative path (still `/`-normalized) when nothing can
+ * be canonicalized — a raw realpath errno logs and returns; ENOENT all the way to
+ * the filesystem root returns silently. The caller's lexical reserved check still
+ * stands in the fallback. `realpath` and the path flavor `p` are injectable so the
+ * fault branches AND the win32 separator normalization can be tested
+ * deterministically from any platform.
+ *
+ * Sibling primitive: `assertRealpathWithinDir` in `symlink-guard.ts` answers the
+ * same realpath-then-refuse-`.ok`/`.git` question with two deliberate
+ * differences — it matches only ROOT-level `.git`/`.ok` (nested `<folder>/.ok/`
+ * is a first-class shape there) where `isReservedProjectStatePath` matches at any
+ * depth, and it resolves dangling symlink leaves manually via `lstat`/`readlink`
+ * with a step cap where this helper's ENOENT branch climbs by `dirname`. Harden
+ * one and check whether the other needs the same change.
+ */
+export function canonicalRelPathForNewTarget(
+ fullPath: string,
+ resolvedContentDir: string,
+ log: PinoLogger,
+ realpath: typeof realpathSync = realpathSync,
+ p: Pick<typeof import('node:path').posix, 'join' | 'relative' | 'dirname' | 'sep'> = {
+ join,
+ relative,
+ dirname,
+ sep,
+ },
+): string {
+ const toPosix = (s: string): string => s.split(p.sep).join('/');
+ let contentRoot: string;
+ try {
+ contentRoot = realpath(resolvedContentDir);
+ } catch (err) {
+ // ENOENT (content dir not created yet) is benign; anything else means the
+ // anchor could not be canonicalized and the check may be stale — worth a warn.
+ if (errnoCode(err) !== 'ENOENT') logCanonicalizationFault(log, resolvedContentDir, err);
+ contentRoot = resolvedContentDir;
+ }
+ let cur = fullPath;
+ for (;;) {
+ try {
+ const canonicalAncestor = realpath(cur);
+ const canonicalFull = p.join(canonicalAncestor, p.relative(cur, fullPath));
+ return toPosix(p.relative(contentRoot, canonicalFull));
+ } catch (err) {
+ if (errnoCode(err) !== 'ENOENT') {
+ logCanonicalizationFault(log, cur, err);
+ return toPosix(p.relative(contentRoot, fullPath));
+ }
+ const parent = p.dirname(cur);
+ if (parent === cur) return toPosix(p.relative(contentRoot, fullPath));
+ cur = parent;
+ }
+ }
+}
+
export function isAlreadyExistsError(err: unknown): boolean {
const code = errnoCode(err);
// Node's cpSync distinguishes the destination-occupied cases by the type
diff --git a/packages/server/src/http/file-ops-routes.test.ts b/packages/server/src/http/file-ops-routes.test.ts
new file mode 100644
index 000000000..1ea0a5f96
--- /dev/null
+++ b/packages/server/src/http/file-ops-routes.test.ts
@@ -0,0 +1,187 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { Readable } from 'node:stream';
+import type { Hocuspocus } from '@hocuspocus/server';
+import { describe, expect, test } from 'vitest';
+import { SymlinkEscapeError } from '../apply-managed-rename.ts';
+import { DocInConflictError } from '../conflict-errors.ts';
+import { ContentRootUnavailableError } from '../fs-safety.ts';
+import { loggerFactory } from '../logger.ts';
+import type { AssetService } from '../services/assets.ts';
+import type { FileOpsService } from '../services/file-ops.ts';
+import { createFileOpsRoutes } from './file-ops-routes.ts';
+
+/**
+ * Table-level pins for the file-ops group's mutating declaration. The wire
+ * cannot pin this: the read half of the DNS-rebinding defense applies the
+ * identical loopback + workspace-Host checks to every `/api/*` request, so an
+ * emptied mutating set changes no composition-suite response — only which
+ * gate (and telemetry tag) fires first. The declared membership is pinned
+ * here directly against the legacy `MUTATING_ROUTES` membership it
+ * reproduces: every path in this family mutated, so every path is declared.
+ */
+
+type Deps = Parameters<typeof createFileOpsRoutes>[0];
+
+function buildGroup(overrides: Partial<Deps> = {}) {
+ return createFileOpsRoutes({
+ contentDir: '/nonexistent-content',
+ projectDir: undefined,
+ log: loggerFactory.getLogger('test'),
+ getPrincipal: undefined,
+ contentFilter: undefined,
+ signalChannel: undefined,
+ getSyncEngine: undefined,
+ flushContributors: undefined,
+ // Never dispatched by these pins; the table declaration is what's under
+ // test, and constructing the group must not touch any of these.
+ hocuspocus: {} as Hocuspocus,
+ fileOpsService: {} as FileOpsService,
+ assetService: {} as AssetService,
+ extractAgentIdentity: () => {
+ throw new Error('not dispatched');
+ },
+ recordDerivedDocumentBestEffort: () => Promise.resolve(),
+ invalidateReferencedAssetsCache: () => {},
+ listManagedDocNamesUnderFolderFromDisk: () => [],
+ resolveContentEntryPath: () => {
+ throw new Error('not dispatched');
+ },
+ docNameForFileOperationPath: () => {
+ throw new Error('not dispatched');
+ },
+ withPeriod: (s) => s,
+ toManagedRenamePublicError: () => {
+ throw new Error('not dispatched');
+ },
+ attributeRenameWriteToActor: () => undefined,
+ renameAttributionCounter: () => {
+ throw new Error('not dispatched');
+ },
+ _performAssetRename: () => Promise.reject(new Error('not dispatched')),
+ _performDocumentToFileRename: () => Promise.reject(new Error('not dispatched')),
+ _performManagedRenameForDocs: () => Promise.reject(new Error('not dispatched')),
+ isValidRelativeContentPath: () => false,
+ ...overrides,
+ });
+}
+
+function makeReq(url: string, body: unknown): IncomingMessage {
+ const readable = Readable.from(Buffer.from(JSON.stringify(body))) as unknown as IncomingMessage;
+ readable.method = 'POST';
+ readable.url = url;
+ readable.headers = { host: 'localhost', 'content-type': 'application/json' };
+ return readable;
+}
+
+function makeRes(): { res: ServerResponse; captured: { status: number; body: string } } {
+ const captured = { status: 0, body: '' };
+ const res = {
+ writeHead(status: number) {
+ captured.status = status;
+ },
+ end(body?: string) {
+ captured.body = body ?? '';
+ },
+ } as unknown as ServerResponse;
+ return { res, captured };
+}
+
+const FAMILY_PATHS = [
+ '/api/create-page',
+ '/api/create-folder',
+ '/api/duplicate-path',
+ '/api/rename-path',
+ '/api/delete-path',
+ '/api/trash/cleanup',
+ '/api/upload',
+];
+
+describe('createFileOpsRoutes table', () => {
+ test('registers exactly the seven file-ops paths', () => {
+ expect([...buildGroup().paths].sort()).toEqual([...FAMILY_PATHS].sort());
+ });
+
+ test('every path in the family is mutating (whole-family legacy MUTATING_ROUTES membership)', () => {
+ const { table } = buildGroup();
+ for (const path of FAMILY_PATHS) {
+ expect(table.isMutating(path), path).toBe(true);
+ }
+ });
+});
+
+describe('rename-path conflict envelope', () => {
+ // When the managed-rename spine throws `DocInConflictError`, the rename-path
+ // branch must return the documented 409 doc-in-conflict envelope rather than
+ // fall through `toManagedRenamePublicError` to a generic 500. Injecting a
+ // throwing spine pins that catch directly.
+ test('maps a DocInConflictError from the rewrite spine to a 409 doc-in-conflict', async () => {
+ const group = buildGroup({
+ hocuspocus: { documents: new Map() } as unknown as Hocuspocus,
+ docNameForFileOperationPath: () => 'a',
+ isValidRelativeContentPath: () => true,
+ _performManagedRenameForDocs: () =>
+ Promise.reject(new DocInConflictError({ file: 'referrer.md' })),
+ });
+ const resolved = group.table.resolve('/api/rename-path');
+ if (!resolved?.dispatch) throw new Error('rename-path did not resolve to a dispatch handler');
+ const { res, captured } = makeRes();
+ await resolved.dispatch(
+ makeReq('/api/rename-path', { kind: 'file', fromPath: 'a', toPath: 'b' }),
+ res,
+ );
+ expect(captured.status).toBe(409);
+ expect((JSON.parse(captured.body) as { type?: string }).type).toBe(
+ 'urn:ok:error:doc-in-conflict',
+ );
+ });
+});
+
+describe('create-page path-resolution error classification', () => {
+ // The create-page containment catch discriminates the WIDER throw set of
+ // `resolveContentEntryPath`: a client-side containment rejection (grouped by
+ // `isContainmentRejection` — the lexical `PathContainmentError` or the
+ // realpath `SymlinkEscapeError`) is a 400 path-escape, but a raw realpath
+ // errno that `assertNoSymlinkEscape` rethrows by contract must reach the
+ // handler's outer catch as a 500 — never be flattened into a client 400.
+ async function dispatchCreatePage(resolveContentEntryPath: () => never) {
+ const group = buildGroup({ resolveContentEntryPath });
+ const resolved = group.table.resolve('/api/create-page');
+ if (!resolved?.dispatch) throw new Error('create-page did not resolve to a dispatch handler');
+ const { res, captured } = makeRes();
+ await resolved.dispatch(makeReq('/api/create-page', { path: 'notes/x.md' }), res);
+ return captured;
+ }
+
+ test('a SymlinkEscapeError maps to a 400 path-escape', async () => {
+ const captured = await dispatchCreatePage(() => {
+ throw new SymlinkEscapeError('path resolves outside content directory');
+ });
+ expect(captured.status).toBe(400);
+ expect((JSON.parse(captured.body) as { type?: string }).type).toBe('urn:ok:error:path-escape');
+ });
+
+ test('a ContentRootUnavailableError surfaces as a 500, not a 400', async () => {
+ // The missing-anchor condition is a server fault (dir deleted under a
+ // running server); `isContainmentRejection` excludes it, so it must reach
+ // the outer catch, never be flattened into the caller's path-escape.
+ const captured = await dispatchCreatePage(() => {
+ throw new ContentRootUnavailableError('content directory does not exist');
+ });
+ expect(captured.status).toBe(500);
+ expect((JSON.parse(captured.body) as { type?: string }).type).toBe(
+ 'urn:ok:error:internal-server-error',
+ );
+ });
+
+ test('a raw realpath errno surfaces as a 500, not a 400', async () => {
+ const captured = await dispatchCreatePage(() => {
+ const err = new Error('EACCES: permission denied, stat') as NodeJS.ErrnoException;
+ err.code = 'EACCES';
+ throw err;
+ });
+ expect(captured.status).toBe(500);
+ expect((JSON.parse(captured.body) as { type?: string }).type).toBe(
+ 'urn:ok:error:internal-server-error',
+ );
+ });
+});
diff --git a/packages/server/src/http/file-ops-routes.ts b/packages/server/src/http/file-ops-routes.ts
new file mode 100644
index 000000000..108d6a3ca
--- /dev/null
+++ b/packages/server/src/http/file-ops-routes.ts
@@ -0,0 +1,2003 @@
+/**
+ * The file-ops family — `create-page`, `create-folder`, `duplicate-path`,
+ * `rename-path`, `delete-path`, `trash/cleanup`, and multipart `upload` —
+ * natively routed as one group. What the handlers share with the rest of the
+ * extension (the FileOpsService/AssetService instances, the managed-rename
+ * spine, attribution + telemetry helpers) arrives as
+ * {@link FileOpsRouteDeps}.
+ *
+ * Every path in the family mutates, so the whole group rides the
+ * loopback/workspace-Host mutating gate.
+ *
+ * `/api/upload` is multipart: its body never touches the shared JSON body
+ * reader — busboy streams it to a tempfile via `readUploadBody`, and the
+ * metadata fields validate post-assembly through `validateBody`.
+ *
+ * `rename-path` here is only the ROUTE + handler shell: the managed-rename
+ * spine (`_performManagedRenameForDocs` and its two asset siblings) stays in
+ * `api-extension.ts` because of its CRDT/sessionManager paired-write
+ * coupling — routing is orthogonal to those internals, so the shell lives
+ * here and the spine is injected.
+ */
+
+import {
+ createWriteStream,
+ type Dirent,
+ existsSync,
+ readdirSync,
+ readFileSync,
+ unlinkSync,
+} from 'node:fs';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { dirname, extname, resolve, sep } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import type { Hocuspocus } from '@hocuspocus/server';
+import {
+ CreateFolderRequestSchema,
+ CreateFolderSuccessSchema,
+ CreatePageRequestSchema,
+ CreatePageSuccessSchema,
+ DeletePathRequestSchema,
+ DeletePathSuccessSchema,
+ DuplicatePathRequestSchema,
+ DuplicatePathSuccessSchema,
+ instantiateDoc,
+ isManagedArtifactDocName,
+ LINKABLE_ASSET_EXTENSIONS,
+ type Principal,
+ type ProblemType,
+ RenamePathRequestSchema,
+ RenamePathSuccessSchema,
+ TrashCleanupRequestSchema,
+ TrashCleanupSuccessSchema,
+ UploadAssetSuccessSchema,
+ UploadRequestSchema,
+} from '@inkeep/open-knowledge-core';
+import { formatRenameSubject } from '@inkeep/open-knowledge-core/shadow-repo-layout';
+import type { SummaryResponse } from '../agent-write-summary.ts';
+import { ManagedRenameCollisionError } from '../apply-managed-rename.ts';
+import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';
+import { DocInConflictError, isDocInConflict, respondDocInConflict } from '../conflict-errors.ts';
+import { isReservedProjectStatePath } from '../content/managed-doc-enum.ts';
+import { applySubstitution, todayIsoUtc } from '../content/substitution.ts';
+import { resolveTemplatesAvailable } from '../content/templates-resolver.ts';
+import type { ContentFilter } from '../content-filter.ts';
+import { recordContributor } from '../contributor-tracker.ts';
+import {
+ docNameToRelativePath,
+ getDocExtension,
+ isSupportedAssetFile,
+ isSupportedDocFile,
+ registerDocExtension,
+ SUPPORTED_DOC_EXTENSIONS,
+ stripDocExtension,
+} from '../doc-extensions.ts';
+import { extractActorIdentity } from '../extract-actor-identity.ts';
+import { canonicalRelPathForNewTarget, isContainmentRejection } from '../fs-safety.ts';
+import { classifyFsPath, normalizeFsPath } from '../fs-traced.ts';
+import type { PinoLogger } from '../logger.ts';
+import { createMultipartParser, type MultipartParser } from '../multipart.ts';
+import type { AssetService } from '../services/assets.ts';
+import { DuplicateNameExhaustedError, type FileOpsService } from '../services/file-ops.ts';
+import type { SyncEngine } from '../sync-engine.ts';
+import { type getMeter, withSpan } from '../telemetry.ts';
+import {
+ classifyUploadErrno,
+ UploadWriteError,
+ type UploadWriteReason,
+ uploadStatusFor,
+ uploadTitleFor,
+} from '../upload-errors.ts';
+import { HashingPassThrough, mintTempUploadPath } from '../upload-streaming.ts';
+import { type ApiRouteGroup, createApiRouteGroup } from './api-pipeline.ts';
+import { errorResponse, type HttpErrorStatus } from './error-response.ts';
+import { errnoCode } from './handler-utils.ts';
+import { getRequestId } from './request-id.ts';
+import { validateBody, withValidation } from './request-validation.ts';
+import { successResponse } from './success-response.ts';
+
+/** Result-shape of the managed-rename spine, shared with `api-extension.ts`. */
+export interface RenamedDocMapping {
+ fromDocName: string;
+ toDocName: string;
+}
+
+export interface RenamedAssetMapping {
+ fromPath: string;
+ toPath: string;
+}
+
+export interface ManagedRenameRewrittenDoc {
+ docName: string;
+ rewrites: number;
+}
+
+/**
+ * True when `path` is one of the synthetic top-level folders (`__system__`,
+ * `__config__`, `__user__`, `__local__`) or lives under one — the reserved
+ * folder-name set that create/rename must refuse. Distinct from
+ * `isReservedProjectStatePath`, which gates the `.ok`/`.git` state dirs.
+ */
+function isReservedSyntheticFolderPath(path: string): boolean {
+ return (
+ path === '__system__' ||
+ path === '__config__' ||
+ path === '__user__' ||
+ path === '__local__' ||
+ path.startsWith('__system__/') ||
+ path.startsWith('__config__/') ||
+ path.startsWith('__user__/') ||
+ path.startsWith('__local__/')
+ );
+}
+
+type DuplicatePathFilesystemProblem = {
+ status: 500 | 507;
+ type: Extract<ProblemType, 'urn:ok:error:storage-full' | 'urn:ok:error:storage-readonly'>;
+ title: string;
+};
+
+function classifyDuplicatePathFilesystemProblem(
+ err: unknown,
+): DuplicatePathFilesystemProblem | null {
+ const code = errnoCode(err);
+ if (code === 'ENOSPC' || code === 'EDQUOT') {
+ return {
+ status: 507,
+ type: 'urn:ok:error:storage-full',
+ title: 'Could not duplicate path because storage is full.',
+ };
+ }
+ if (code === 'EPERM' || code === 'EACCES' || code === 'EROFS') {
+ return {
+ status: 500,
+ type: 'urn:ok:error:storage-readonly',
+ title: 'Could not duplicate path because storage is not writable.',
+ };
+ }
+ return null;
+}
+
+type RenameAttributionActor = Exclude<
+ ReturnType<typeof extractActorIdentity>,
+ { kind: 'invalid-summary' }
+>;
+
+interface UploadResult {
+ filename: string;
+ mimeType: string;
+ parentDocName: string;
+ placement: string;
+ tempPath: string;
+ sha: string;
+ byteLength: number;
+}
+
+/**
+ * Stream multipart upload body to a tempfile while hashing on-the-fly.
+ *
+ * Replaces the buffer-to-memory pattern (chunks.push(chunk) +
+ * Buffer.concat) with busboy's streaming 'file' event piped through a
+ * HashingPassThrough Transform into createWriteStream(tempPath). Memory
+ * becomes O(1); disk is the only bound.
+ *
+ * Error contract (typed via UploadWriteError.reason — URN-form ProblemType):
+ * - urn:ok:error:malformed-upload: busboy 'error' (unparseable multipart, etc.)
+ * - urn:ok:error:storage-full: ENOSPC / EDQUOT during the write stream
+ * - urn:ok:error:storage-readonly: EROFS / EACCES / EPERM during the write stream
+ * - urn:ok:error:storage-error: any other write-stream error
+ *
+ * On any error, the tempfile is best-effort unlinked before propagating.
+ */
+function readUploadBody(req: IncomingMessage, projectDir: string): Promise<UploadResult> {
+ return new Promise((resolveP, reject) => {
+ let bb: MultipartParser;
+ try {
+ // `files: 1` caps the file part; `fields` + `fieldSize` cap non-file
+ // surface so a flooded multipart can't buffer thousands of fields or a
+ // multi-MB string field in memory before the upload body resolves. The
+ // legitimate schema (agentId / docName / position / summary) is bounded
+ // — short identifiers, never approaching 2 KB or 10 entries. The
+ // ENAMETOOLONG-via-crafted-filename DoS path is closed by the 255-byte
+ // ceiling in `sanitizeFilename` (the filesystem-portability layer);
+ // busboy does not expose a header-section-size limit (only headerPairs
+ // count), so the parsed-value cap is the right place.
+ bb = createMultipartParser(req, { files: 1, fields: 10, fieldSize: 2 * 1024 });
+ } catch (err) {
+ reject(new UploadWriteError('urn:ok:error:malformed-upload', err));
+ return;
+ }
+
+ let settled = false;
+ let filename = 'upload';
+ let mimeType = '';
+ let parentDocName = '';
+ let placement = '';
+ let tempPath: string | undefined;
+ let writeStream: ReturnType<typeof createWriteStream> | undefined;
+ let pipelineError: unknown;
+ // Track whether the 'file' event ever fired. busboy emits 'close' as
+ // soon as it finishes parsing the request body — but the file
+ // pipeline (createWriteStream + HashingPassThrough) is async and may
+ // still be running when 'close' fires. We must NOT resolve to an
+ // empty UploadResult on 'close' when a file IS being processed; the
+ // pipeline `.then()` is the legitimate resolver in that case. Only
+ // the no-file path needs the 'close' fallback.
+ let fileEventFired = false;
+
+ // Mint the tempfile path lazily on the first 'file' event — busboy
+ // can fire 'error' before any file arrives (e.g. missing boundary)
+ // and we'd otherwise create a zero-byte tempfile for no reason.
+
+ const fail = (reason: UploadWriteReason, cause: unknown) => {
+ if (settled) return;
+ settled = true;
+ // Destroy the write stream BEFORE the unlink: `unlink()` only removes
+ // the directory entry, so an fd left open by a mid-stream disconnect
+ // would pin the inode's disk blocks (and leak the fd) for the rest of
+ // the process's uptime — the boot-time orphan sweep readdirs the
+ // staging dir and cannot see an already-unlinked file. Destroying also
+ // settles the `pipeline()` promise; its `.catch` re-enters `fail()` as
+ // a no-op via the `settled` guard.
+ //
+ // `destroy()` schedules the fd close on a later tick, so the synchronous
+ // unlink below still runs against an open handle. On POSIX that is fine —
+ // the entry goes away and the inode is reclaimed when the deferred close
+ // lands. On platforms with mandatory locking (Windows) that unlink fails
+ // with the handle open, so also retry once the stream has actually
+ // closed; there, the close-ordered retry (not the sync call) is what
+ // drains the staging dir.
+ if (writeStream && tempPath) {
+ const staged = tempPath;
+ writeStream.once('close', () => {
+ try {
+ unlinkSync(staged);
+ } catch {
+ // already gone — the synchronous unlink won (the POSIX path)
+ }
+ });
+ }
+ writeStream?.destroy();
+ if (tempPath) {
+ try {
+ unlinkSync(tempPath);
+ } catch {
+ // best-effort; the close-ordered retry above covers open-handle
+ // platforms, and the orphan sweep catches any remaining stragglers
+ }
+ }
+ reject(cause instanceof UploadWriteError ? cause : new UploadWriteError(reason, cause));
+ };
+
+ const classifyWriteError = classifyUploadErrno;
+
+ bb.on('field', (name, val) => {
+ if (name === 'parentDocName') parentDocName = val;
+ if (name === 'placement') placement = val;
+ });
+
+ bb.on('file', (_fieldname, file, info) => {
+ fileEventFired = true;
+ filename = info.filename || 'upload';
+ mimeType = info.mimeType || '';
+
+ // `mintTempUploadPath` does `tracedMkdirSync(.., { recursive: true })`
+ // which can throw ENOSPC / EDQUOT / EROFS / EACCES / EPERM / EIO. An
+ // uncaught throw here bubbles back through busboy's `_write` and
+ // re-emits as `'error'`, which the listener below classifies as
+ // `'urn:ok:error:malformed-upload'` (HTTP 400). That misleads operators triaging
+ // a full disk into chasing a phantom client bug. Catch the sync
+ // throw, classify via the same table the pipeline rejection uses,
+ // and drain the file part so busboy can finish parsing the rest.
+ let path: string;
+ try {
+ path = mintTempUploadPath(projectDir);
+ } catch (err) {
+ const nodeErr = err as NodeJS.ErrnoException;
+ fail(classifyWriteError(nodeErr), err as Error);
+ file.resume();
+ return;
+ }
+ tempPath = path;
+ const hasher = new HashingPassThrough();
+ writeStream = createWriteStream(path);
+
+ pipeline(file, hasher, writeStream)
+ .then(() => {
+ if (settled) return;
+ settled = true;
+ resolveP({
+ filename,
+ mimeType,
+ parentDocName,
+ placement,
+ tempPath: path,
+ sha: hasher.digest(),
+ byteLength: hasher.byteLength(),
+ });
+ })
+ .catch((err) => {
+ pipelineError = err;
+ // Classify from the deepest write error if available; otherwise
+ // treat as a generic storage-error. The unlink happens inside fail().
+ const nodeErr = err as NodeJS.ErrnoException;
+ fail(classifyWriteError(nodeErr), err);
+ });
+ });
+
+ bb.on('error', (err) => {
+ fail('urn:ok:error:malformed-upload', err);
+ });
+
+ // busboy's `close` (Writable, emitClose:true via @types/[email protected])
+ // fires once busboy finishes parsing the request body. If by then
+ // no `file` event ever fired, the request was a well-formed
+ // multipart with fields-only (no file part) — resolve with a
+ // synthetic empty UploadResult so the route handler's
+ // `byteLength === 0` guard returns the standard 400 "No file
+ // received." Without this hook the Promise never settles on fields-
+ // only uploads and the connection hangs until Node's request
+ // timeout fires (DoS).
+ //
+ // CRUCIAL: gate on `!fileEventFired`. If a file part IS present,
+ // busboy emits 'close' as soon as it finishes parsing — but the
+ // async write/hash pipeline below may still be running. Resolving
+ // here would race the pipeline's legitimate resolveP and produce a
+ // spurious empty result. Pipeline resolves win in that case.
+ bb.on('close', () => {
+ if (settled || pipelineError) return;
+ if (fileEventFired) return;
+ settled = true;
+ resolveP({
+ filename: '',
+ mimeType: '',
+ parentDocName,
+ placement,
+ tempPath: '',
+ sha: '',
+ byteLength: 0,
+ });
+ });
+
+ // Guard the "client disconnected mid-stream" path. busboy never
+ // reaches `_final` if the request aborts before the closing boundary,
+ // so its `close` would not fire and the Promise would otherwise hang.
+ req.on('close', () => {
+ if (settled || pipelineError) return;
+ if (!req.complete) {
+ fail('urn:ok:error:malformed-upload', new Error('client disconnected'));
+ }
+ });
+
+ req.pipe(bb);
+ });
+}
+
+/**
+ * Everything the seven handlers used to reach through the extension closure.
+ * Function-shaped deps keep their extension-side names so the handler bodies
+ * read unchanged.
+ */
+export interface FileOpsRouteDeps {
+ contentDir: string;
+ projectDir: string | undefined;
+ log: PinoLogger;
+ getPrincipal: (() => Principal | null) | undefined;
+ contentFilter: ContentFilter | undefined;
+ signalChannel: ((channel: 'files' | 'lint-config' | 'comments') => void) | undefined;
+ hocuspocus: Hocuspocus;
+ getSyncEngine: (() => SyncEngine | null) | undefined;
+ flushContributors: (() => Promise<void>) | undefined;
+ fileOpsService: FileOpsService;
+ assetService: AssetService;
+ extractAgentIdentity: (body: Record<string, unknown>) => {
+ rawAgentId: string | undefined;
+ agentId: string;
+ agentName: string;
+ colorSeed: string;
+ clientName: string | undefined;
+ clientVersion: string | undefined;
+ label: string | undefined;
+ };
+ recordDerivedDocumentBestEffort: (
+ documentName: string,
+ markdown: string,
+ reason: string,
+ ) => Promise<void>;
+ invalidateReferencedAssetsCache: () => void;
+ listManagedDocNamesUnderFolderFromDisk: (sourcePathRoot: string) => string[];
+ resolveContentEntryPath: (contentDir: string, kind: 'file' | 'folder', path: string) => string;
+ docNameForFileOperationPath: (contentDir: string, relPath: string) => string;
+ withPeriod: (s: string) => string;
+ toManagedRenamePublicError: (error: unknown) => {
+ status: HttpErrorStatus;
+ type: ProblemType;
+ error: string;
+ };
+ attributeRenameWriteToActor: (
+ actor: RenameAttributionActor,
+ defaultSummarySubject: string,
+ entries: readonly { docName: string; subject: string }[],
+ options: { context: string; onAnonymous?: () => void },
+ ) => SummaryResponse | undefined;
+ renameAttributionCounter: () => ReturnType<ReturnType<typeof getMeter>['createCounter']>;
+ _performAssetRename: (
+ fromPath: string,
+ toPath: string,
+ ) => Promise<{
+ renamedAssets: RenamedAssetMapping[];
+ rewrittenDocs: ManagedRenameRewrittenDoc[];
+ }>;
+ _performDocumentToFileRename: (
+ fromPath: string,
+ toPath: string,
+ ) => Promise<{
+ renamedAssets: RenamedAssetMapping[];
+ rewrittenDocs: ManagedRenameRewrittenDoc[];
+ }>;
+ _performManagedRenameForDocs: (
+ fromPath: string,
+ toPath: string,
+ kind: 'file' | 'folder',
+ options?: {
+ actor?: {
+ writerId: string;
+ displayName: string;
+ colorSeed?: string;
+ actorMetadata?: {
+ principalId?: string;
+ agentType?: string;
+ clientName?: string;
+ clientVersion?: string;
+ label?: string;
+ };
+ };
+ },
+ ) => Promise<{
+ renamed: RenamedDocMapping[];
+ renamedAssets: RenamedAssetMapping[];
+ rewrittenDocs: ManagedRenameRewrittenDoc[];
+ }>;
+ isValidRelativeContentPath: (path: string) => boolean;
+}
+
+export function createFileOpsRoutes(deps: FileOpsRouteDeps): ApiRouteGroup {
+ const {
+ contentDir,
+ projectDir,
+ log,
+ getPrincipal,
+ contentFilter,
+ signalChannel,
+ hocuspocus,
+ getSyncEngine,
+ flushContributors,
+ fileOpsService,
+ assetService,
+ extractAgentIdentity,
+ recordDerivedDocumentBestEffort,
+ invalidateReferencedAssetsCache,
+ listManagedDocNamesUnderFolderFromDisk,
+ resolveContentEntryPath,
+ docNameForFileOperationPath,
+ withPeriod,
+ toManagedRenamePublicError,
+ attributeRenameWriteToActor,
+ renameAttributionCounter,
+ _performAssetRename,
+ _performDocumentToFileRename,
+ _performManagedRenameForDocs,
+ isValidRelativeContentPath,
+ } = deps;
+
+ /**
+ * True when a request path — clean of `.ok`/`.git` segments lexically —
+ * CANONICALLY resolves into a reserved subtree, i.e. a symlinked directory
+ * routes it into `.ok`/`.git` without an escape (the realpath stays inside the
+ * content root, so `assertNoSymlinkEscape` admits it). Consumers: create-folder,
+ * duplicate-path, rename-path (source and destination), delete-path, and
+ * upload; create-page runs the same check through its own inline
+ * `canonicalRelPathForNewTarget` call, since it already holds a resolved
+ * `fullPath`. The guard is judged by where the operation ACTUALLY lands, not
+ * the lexical request string. Resolves the path verbatim (`kind: 'folder'`, no
+ * extension munging) purely to obtain the on-disk location. When resolution
+ * itself throws the canonical location is unknowable, so this returns `false`.
+ * That swallow is safe ONLY because every consumer runs
+ * `isValidRelativeContentPath` (and 400s) BEFORE this gate — upload validates
+ * and passes the parent directory component, since its basename is a raw
+ * filename it never resolves — so the paths that reach it cannot fail the
+ * lexical half of resolution; a
+ * genuinely non-lexical fault then re-raises in the route's own downstream
+ * resolution, where a containment rejection maps to 400 path-escape via each
+ * route's `isContainmentRejection` arm and a raw errno to the typed 500.
+ * Upload's downstream check is destination-side instead: `storeUpload`'s
+ * `reserved-destination` outcome on the resolved dest dir.
+ */
+ const canonicalTargetIsReserved = (lexicalRelPath: string): boolean => {
+ let fullPath: string;
+ try {
+ fullPath = resolveContentEntryPath(contentDir, 'folder', lexicalRelPath);
+ } catch {
+ return false;
+ }
+ return isReservedProjectStatePath(
+ canonicalRelPathForNewTarget(fullPath, resolve(contentDir), log),
+ );
+ };
+
+ /**
+ * Probe disk for the actual on-disk extension of a file's docName, registering
+ * it in the doc-extensions map if found. Closes a boot/watcher race where the
+ * rename handler runs before the file watcher has observed the source — without
+ * this, `getDocExtension()` returns the `.md` default, which silently defeats
+ * `.mdx`-specific exclusion patterns and routes existence checks to the wrong
+ * path. Iterating in `SUPPORTED_DOC_EXTENSIONS` precedence order ensures the
+ * `.mdx` precedence rule is preserved when both files exist on disk.
+ * Idempotent — `registerDocExtension` is a no-op when the higher-precedence
+ * extension is already registered.
+ */
+ function probeAndRegisterSourceFileExtension(probeContentDir: string, fromPath: string): void {
+ if (!isValidRelativeContentPath(fromPath)) return;
+ const resolvedContentDir = resolve(probeContentDir);
+ if (isSupportedDocFile(fromPath)) {
+ const extensionless = stripDocExtension(fromPath);
+ for (const ext of SUPPORTED_DOC_EXTENSIONS) {
+ const candidate = resolve(resolvedContentDir, `${extensionless}${ext}`);
+ if (
+ candidate !== resolvedContentDir &&
+ !candidate.startsWith(`${resolvedContentDir}${sep}`)
+ ) {
+ continue;
+ }
+ if (existsSync(candidate)) {
+ registerDocExtension(extensionless, ext);
+ }
+ }
+ const explicitCandidate = resolve(resolvedContentDir, fromPath);
+ if (
+ explicitCandidate !== resolvedContentDir &&
+ explicitCandidate.startsWith(`${resolvedContentDir}${sep}`) &&
+ existsSync(explicitCandidate)
+ ) {
+ registerDocExtension(extensionless, extname(fromPath));
+ }
+ return;
+ }
+ for (const ext of SUPPORTED_DOC_EXTENSIONS) {
+ const candidate = resolve(resolvedContentDir, `${fromPath}${ext}`);
+ if (
+ candidate !== resolvedContentDir &&
+ !candidate.startsWith(`${resolvedContentDir}${sep}`)
+ ) {
+ continue;
+ }
+ if (existsSync(candidate)) {
+ registerDocExtension(fromPath, ext);
+ return;
+ }
+ }
+ }
+
+ function resolveExtensionlessAssetPath(assetPath: string): {
+ path: string;
+ ambiguous: boolean;
+ } {
+ // Filesystem-backed authority for extensionless asset targets; the client
+ // canonicalizer is only a UX aid for dialogs and shell-trash paths.
+ if (extname(assetPath)) return { path: assetPath, ambiguous: false };
+
+ const slash = assetPath.lastIndexOf('/');
+ const parent = slash === -1 ? '' : assetPath.slice(0, slash);
+ const stem = slash === -1 ? assetPath : assetPath.slice(slash + 1);
+ const parentPath = parent ? resolveContentEntryPath(contentDir, 'folder', parent) : contentDir;
+
+ let entries: Dirent[];
+ try {
+ entries = readdirSync(parentPath, { withFileTypes: true });
+ } catch (err) {
+ const code = errnoCode(err);
+ if (code === 'ENOENT' || code === 'ENOTDIR') {
+ return { path: assetPath, ambiguous: false };
+ }
+ throw err;
+ }
+
+ const candidates = entries
+ .filter((entry) => entry.isFile() && entry.name.startsWith(`${stem}.`))
+ .map((entry) => (parent ? `${parent}/${entry.name}` : entry.name))
+ .filter((candidate) => isSupportedAssetFile(candidate, LINKABLE_ASSET_EXTENSIONS));
+
+ if (candidates.length === 1) return { path: candidates[0], ambiguous: false };
+ return { path: assetPath, ambiguous: candidates.length > 1 };
+ }
+
+ const handleCreatePage = withValidation(
+ CreatePageRequestSchema,
+ async (_req, res, body) => {
+ try {
+ const bodyObj = body as unknown as Record<string, unknown>;
+ // Identity boundary: only attribute when the caller explicitly supplies
+ // agentId. UI-driven creates fall through to the loaded principal (if
+ // any) or anonymous — never to a synthetic 'Claude' default. Mirrors
+ // handleRollback / handleRenamePath.
+ const actor = extractActorIdentity(bodyObj, getPrincipal);
+ if (actor.kind === 'invalid-summary') {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
+ handler: 'create-page',
+ });
+ return;
+ }
+
+ const filePath = body.path;
+ if (!isSupportedDocFile(filePath)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'path must end with .md or .mdx.',
+ { handler: 'create-page' },
+ );
+ return;
+ }
+ if (
+ filePath.includes('..') ||
+ filePath.startsWith('/') ||
+ filePath.includes('\x00') ||
+ filePath.includes('\\')
+ ) {
+ errorResponse(res, 400, 'urn:ok:error:path-escape', 'Invalid path.', {
+ handler: 'create-page',
+ detail: 'path must not contain .. or start with /',
+ });
+ return;
+ }
+ // Same containment core as the five sibling routes: lexical prefix
+ // check PLUS the realpath symlink-escape refusal. A hand-rolled
+ // resolve + prefix pair here would admit a write through a symlinked
+ // directory pointing outside the content root.
+ const resolvedContentDir = resolve(contentDir);
+ let fullPath: string;
+ try {
+ fullPath = resolveContentEntryPath(contentDir, 'file', filePath);
+ } catch (err) {
+ // `resolveContentEntryPath` throws a WIDER set than the old lexical
+ // check it replaced. `isContainmentRejection` is exactly the
+ // caller-fault set — the lexical `PathContainmentError` plus the
+ // realpath `SymlinkEscapeError` — which maps to a 400 path-escape.
+ // Everything else (notably the raw realpath errnos
+ // `assertNoSymlinkEscape` rethrows by contract — EPERM/EACCES/EIO/
+ // ESTALE) is an infrastructure fault and must reach the handler's
+ // outer catch as a typed 500, not a misleading client 400.
+ if (isContainmentRejection(err)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:path-escape',
+ 'path must not escape content directory.',
+ { handler: 'create-page', cause: err },
+ );
+ return;
+ }
+ throw err;
+ }
+ const candidateDocName = stripDocExtension(filePath);
+ if (isSystemDoc(candidateDocName) || isConfigDoc(candidateDocName)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ `'${candidateDocName}' is a reserved document name.`,
+ { handler: 'create-page' },
+ );
+ return;
+ }
+ // Reject managed-artifact + reserved-directory targets. Now that
+ // `.ok/skills/**` is indexed/served content, a raw create-page into
+ // `.ok/skills/<name>/SKILL.md` would write directly with ZERO skill-schema
+ // validation (no name/description checks, no XML-tag ban) and surface as a
+ // malformed phantom skill. Skills/templates must go through their own
+ // validating write/install spines; every other `.ok/` child is excluded
+ // from the content scope anyway. The reserved-path test catches raw
+ // filesystem paths with a `.ok`/`.git` segment at any depth;
+ // `isManagedArtifactDocName` catches the synthetic `__skill__/` /
+ // `__template__/` doc-name forms.
+ //
+ // `filePath` is the LEXICAL request string, but `resolveContentEntryPath`
+ // resolves with `path.resolve`, which does not follow symlinks — so a
+ // request like `sneaky/x.md`, where `sneaky` is a symlink to `.ok`, has
+ // no `.ok` segment lexically yet physically lands in the reserved
+ // subtree (and does NOT trip the symlink-escape guard, since `.ok` stays
+ // inside the content root). Run the reserved-path test on the CANONICAL
+ // relative path too, so the write is judged by where it actually lands.
+ const canonicalRelPath = canonicalRelPathForNewTarget(fullPath, resolvedContentDir, log);
+ if (
+ isReservedProjectStatePath(filePath) ||
+ isReservedProjectStatePath(canonicalRelPath) ||
+ isManagedArtifactDocName(candidateDocName)
+ ) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ `'${candidateDocName}' is a reserved document name.`,
+ {
+ handler: 'create-page',
+ detail:
+ 'Cannot create a page inside .ok or .git — skills and templates are authored through their own validating flows.',
+ },
+ );
+ return;
+ }
+ // Optional template parameter: when set, instantiate the new
+ // doc from the resolved template's body (with {{date}} / {{user}}
+ // substitution applied) instead of an empty file. Resolution walks
+ // the parent folder's templates_available[] — local + inherited,
+ // closest-wins.
+ const templateName =
+ typeof (body as Record<string, unknown>).template === 'string'
+ ? ((body as Record<string, unknown>).template as string).trim()
+ : '';
+ let initialContent = '';
+ let templateScopeForLog: 'local' | 'inherited' | undefined;
+ if (templateName.length > 0) {
+ if (!/^[A-Za-z0-9_-]+$/.test(templateName)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'Template name must match [A-Za-z0-9_-]+.',
+ { handler: 'create-page' },
+ );
+ return;
+ }
+ const parentFolder = filePath.includes('/')
+ ? filePath.slice(0, filePath.lastIndexOf('/'))
+ : '';
+ const available = resolveTemplatesAvailable(resolvedContentDir, parentFolder);
+ const matched = available.find((t) => t.name === templateName);
+ if (!matched) {
+ const availableLabel =
+ available.length === 0
+ ? '(none)'
+ : available.map((t) => `"${t.name}" (${t.scope})`).join(', ');
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ `Template "${templateName}" does not resolve for folder "${parentFolder || '(root)'}". Available: ${availableLabel}`,
+ { handler: 'create-page' },
+ );
+ return;
+ }
+ // `matched` came from `resolveTemplatesAvailable`, which constrains
+ // every entry to a realpath inside BOTH its own `.ok/templates/`
+ // directory AND the project root (see its containment contract) — a
+ // template symlinked out of the project, or elsewhere inside it such
+ // as `.ok/local/` or `.git/`, is dropped from the menu and so never
+ // resolves here. The read below is therefore already contained; no
+ // per-consumer symlink guard needed.
+ const templateAbs = resolve(resolvedContentDir, matched.path);
+ let templateRaw: string;
+ try {
+ templateRaw = readFileSync(templateAbs, 'utf-8');
+ } catch (err) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ `Failed to read template at ${matched.path}.`,
+ { handler: 'create-page', cause: err },
+ );
+ return;
+ }
+ // The new doc IS the template's starter content (doc-frontmatter +
+ // markdown) with the `template:` identity stripped. `instantiateDoc`
+ // normalizes single-block and legacy two-block templates the same way
+ // and preserves `{{date}}`/`{{user}}` tokens verbatim for substitution.
+ const templateStarter = instantiateDoc(templateRaw);
+ // {{user}} substitutes the calling principal's display name; falls
+ // back to empty string when no principal is loaded.
+ const userDisplayName =
+ actor.kind === 'agent' || actor.kind === 'principal' ? (actor.displayName ?? '') : '';
+ initialContent = applySubstitution(templateStarter, {
+ date: todayIsoUtc(),
+ user: userDisplayName,
+ });
+ templateScopeForLog = matched.scope;
+ }
+
+ const docName = stripDocExtension(filePath);
+ // Synchronous through recordContributor below: an async yield between
+ // the write and the contributor recording lets a pending shadow-commit
+ // timer drain the accumulator without this file's attribution.
+ const createOutcome = fileOpsService.createPage({
+ fullPath,
+ docName,
+ initialContent,
+ });
+ if (!createOutcome.ok) {
+ errorResponse(res, 409, 'urn:ok:error:doc-already-exists', 'File already exists.', {
+ handler: 'create-page',
+ cause: createOutcome.cause,
+ });
+ return;
+ }
+ switch (actor.kind) {
+ case 'agent':
+ case 'principal':
+ recordContributor(
+ docName,
+ actor.writerId,
+ actor.displayName,
+ actor.colorSeed,
+ undefined,
+ actor.actor,
+ );
+ break;
+ case 'anonymous':
+ // UI-driven create with no loaded principal — no contributor recorded.
+ break;
+ default: {
+ const _exhaustive: never = actor;
+ throw new Error(
+ `Unhandled actor kind in handleCreatePage: ${String((_exhaustive as { kind?: unknown }).kind)}`,
+ );
+ }
+ }
+ // Best-effort for real (see the skill-put site): never hold a create
+ // response on the derived-index command queue.
+ void recordDerivedDocumentBestEffort(docName, initialContent, 'create-page');
+ signalChannel?.('files');
+ if (templateScopeForLog !== undefined) {
+ // Cardinality-bounded structured event — `templateScope` is one of
+ // two values; `templateName` is bounded by the user's actual
+ // templates. Mirrors the structured-event style in activity-log.ts.
+ console.warn(
+ JSON.stringify({
+ event: 'template-instantiate',
+ templateName,
+ templateScope: templateScopeForLog,
+ docName,
+ }),
+ );
+ }
+ successResponse(res, 200, CreatePageSuccessSchema, { docName }, { handler: 'create-page' });
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to create page.', {
+ handler: 'create-page',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'create-page', method: 'POST' },
+ );
+
+ const handleCreateFolder = withValidation(
+ CreateFolderRequestSchema,
+ async (_req, res, body) => {
+ try {
+ const bodyObj = body as unknown as Record<string, unknown>;
+ const actor = extractActorIdentity(bodyObj, getPrincipal);
+ if (actor.kind === 'invalid-summary') {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
+ handler: 'create-folder',
+ });
+ return;
+ }
+ const folderPath = body.path;
+ if (!isValidRelativeContentPath(folderPath)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'path must be a relative content path.',
+ { handler: 'create-folder' },
+ );
+ return;
+ }
+ if (isReservedProjectStatePath(folderPath) || canonicalTargetIsReserved(folderPath)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ '.ok and .git are reserved directories.',
+ { handler: 'create-folder' },
+ );
+ return;
+ }
+ if (contentFilter?.isDirExcluded(folderPath)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'Destination folder is excluded by the workspace content config.',
+ { handler: 'create-folder' },
+ );
+ return;
+ }
+
+ const outcome = fileOpsService.createFolder(folderPath);
+ if (!outcome.ok) {
+ errorResponse(res, 409, 'urn:ok:error:doc-already-exists', 'Folder already exists.', {
+ handler: 'create-folder',
+ });
+ return;
+ }
+ successResponse(
+ res,
+ 200,
+ CreateFolderSuccessSchema,
+ { path: folderPath },
+ { handler: 'create-folder' },
+ );
+ } catch (e) {
+ // The service resolves the path lexically-validated only, so a symlink
+ // out of the content root surfaces here as a containment rejection — a
+ // caller fault, mapped to the same 400 create-page and rename-path emit,
+ // never the generic 500 (which mis-logs it as a server fault).
+ if (isContainmentRejection(e)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:path-escape',
+ 'path must not escape content directory.',
+ { handler: 'create-folder', cause: e },
+ );
+ return;
+ }
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to create folder.', {
+ handler: 'create-folder',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'create-folder', method: 'POST' },
+ );
+
+ const handleDuplicatePath = withValidation(
+ DuplicatePathRequestSchema,
+ async (_req, res, body) => {
+ try {
+ const bodyObj = body as unknown as Record<string, unknown>;
+ const actor = extractActorIdentity(bodyObj, getPrincipal);
+ if (actor.kind === 'invalid-summary') {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
+ handler: 'duplicate-path',
+ });
+ return;
+ }
+
+ const { kind } = body;
+ const requestedPath = body.path;
+ const requestedDocName = kind === 'file' ? stripDocExtension(requestedPath) : requestedPath;
+ if (!isValidRelativeContentPath(requestedPath)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'path must be a relative content path.',
+ { handler: 'duplicate-path' },
+ );
+ return;
+ }
+ if (
+ isReservedProjectStatePath(requestedPath) ||
+ canonicalTargetIsReserved(requestedPath) ||
+ (kind === 'file' && (isSystemDoc(requestedDocName) || isConfigDoc(requestedDocName))) ||
+ (kind === 'folder' && isReservedSyntheticFolderPath(requestedPath))
+ ) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ 'Reserved paths cannot be duplicated.',
+ { handler: 'duplicate-path' },
+ );
+ return;
+ }
+
+ if (kind === 'file') {
+ probeAndRegisterSourceFileExtension(contentDir, requestedPath);
+ }
+
+ const outcome = await fileOpsService.duplicatePath(kind, requestedPath, requestedDocName);
+ if (!outcome.ok) {
+ switch (outcome.kind) {
+ case 'not-found':
+ errorResponse(res, 404, 'urn:ok:error:doc-not-found', `${kind} does not exist.`, {
+ handler: 'duplicate-path',
+ });
+ return;
+ case 'type-mismatch':
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ `Target path is not a ${kind}.`,
+ { handler: 'duplicate-path' },
+ );
+ return;
+ case 'conflict':
+ respondDocInConflict(
+ res,
+ new DocInConflictError({ file: outcome.file }),
+ 'duplicate-path',
+ );
+ return;
+ case 'destination-excluded':
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ kind === 'file'
+ ? 'Duplicated document destination is excluded by the project content config.'
+ : 'Duplicated folder destination is excluded by the project content config.',
+ { handler: 'duplicate-path' },
+ );
+ return;
+ case 'already-exists':
+ errorResponse(
+ res,
+ 409,
+ 'urn:ok:error:doc-already-exists',
+ `A ${kind} at the duplicate destination already exists.`,
+ { handler: 'duplicate-path', cause: outcome.cause },
+ );
+ return;
+ default: {
+ const _exhaustive: never = outcome;
+ throw new Error(
+ `Unhandled duplicate outcome: ${String((_exhaustive as { kind?: unknown }).kind)}`,
+ );
+ }
+ }
+ }
+ const { duplicatedPath, duplicatedDocNames } = outcome;
+
+ switch (actor.kind) {
+ case 'agent':
+ case 'principal':
+ for (const docName of duplicatedDocNames) {
+ recordContributor(
+ docName,
+ actor.writerId,
+ actor.displayName,
+ actor.colorSeed,
+ undefined,
+ actor.actor,
+ );
+ }
+ break;
+ case 'anonymous':
+ break;
+ default: {
+ const _exhaustive: never = actor;
+ throw new Error(
+ `Unhandled actor kind in handleDuplicatePath: ${String((_exhaustive as { kind?: unknown }).kind)}`,
+ );
+ }
+ }
+
+ signalChannel?.('files');
+ successResponse(
+ res,
+ 200,
+ DuplicatePathSuccessSchema,
+ { kind, path: duplicatedPath, duplicatedDocNames },
+ { handler: 'duplicate-path' },
+ );
+ } catch (e) {
+ if (e instanceof DuplicateNameExhaustedError) {
+ errorResponse(
+ res,
+ 409,
+ 'urn:ok:error:doc-already-exists',
+ 'All available duplicate name slots are occupied for this path.',
+ { handler: 'duplicate-path', cause: e },
+ );
+ return;
+ }
+ const filesystemProblem = classifyDuplicatePathFilesystemProblem(e);
+ if (filesystemProblem) {
+ errorResponse(
+ res,
+ filesystemProblem.status,
+ filesystemProblem.type,
+ filesystemProblem.title,
+ { handler: 'duplicate-path', cause: e },
+ );
+ return;
+ }
+ if (isContainmentRejection(e)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:path-escape',
+ 'path must not escape content directory.',
+ { handler: 'duplicate-path', cause: e },
+ );
+ return;
+ }
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to duplicate path.', {
+ handler: 'duplicate-path',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'duplicate-path', method: 'POST' },
+ );
+
+ const handleRenamePath = withValidation(
+ RenamePathRequestSchema,
+ async (_req, res, body) => {
+ try {
+ const bodyObj = body as unknown as Record<string, unknown>;
+ const actor = extractActorIdentity(bodyObj, getPrincipal);
+ if (actor.kind === 'invalid-summary') {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
+ handler: 'rename-path',
+ });
+ return;
+ }
+ const { kind, fromPath, toPath } = body;
+ if (!isValidRelativeContentPath(fromPath) || !isValidRelativeContentPath(toPath)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'Paths must be relative content paths.',
+ { handler: 'rename-path' },
+ );
+ return;
+ }
+ if (
+ kind === 'file' &&
+ (isSystemDoc(fromPath) ||
+ isSystemDoc(toPath) ||
+ isConfigDoc(fromPath) ||
+ isConfigDoc(toPath))
+ ) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ 'Reserved document names cannot be renamed.',
+ { handler: 'rename-path' },
+ );
+ return;
+ }
+ // Reject paths with a `.ok` or `.git` segment at any depth — root
+ // `.ok/` holds OK config (`config.yml`, `frontmatter.yml`,
+ // `templates/`) plus the per-machine `local/` runtime subtree
+ // (server.lock, principal.json, cache, etc.), and nested
+ // `<folder>/.ok/` holds folder metadata + templates. Symmetric with
+ // the `__system__` carve-out. The `AGENTS.md` file inside `.ok/` is a
+ // tracked content file by design, but a rename TO or FROM these
+ // directories would clobber OK bookkeeping.
+ if (
+ isReservedProjectStatePath(fromPath) ||
+ isReservedProjectStatePath(toPath) ||
+ canonicalTargetIsReserved(fromPath) ||
+ canonicalTargetIsReserved(toPath)
+ ) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ '.ok and .git are reserved directories.',
+ {
+ handler: 'rename-path',
+ },
+ );
+ return;
+ }
+ if (fromPath === toPath) {
+ successResponse(
+ res,
+ 200,
+ RenamePathSuccessSchema,
+ { renamed: [], renamedAssets: [], rewrittenDocs: [] },
+ { handler: 'rename-path' },
+ );
+ return;
+ }
+ const operationKind =
+ kind === 'asset' && isSupportedDocFile(fromPath) && isSupportedDocFile(toPath)
+ ? 'file'
+ : kind;
+ if (operationKind === 'asset') {
+ let result: {
+ renamedAssets: RenamedAssetMapping[];
+ rewrittenDocs: ManagedRenameRewrittenDoc[];
+ };
+ try {
+ result =
+ isSupportedDocFile(fromPath) && !isSupportedDocFile(toPath)
+ ? await _performDocumentToFileRename(fromPath, toPath)
+ : await _performAssetRename(fromPath, toPath);
+ } catch (err) {
+ if (err instanceof DocInConflictError) {
+ respondDocInConflict(res, err, 'rename-path');
+ return;
+ }
+ const { status, type, error } = toManagedRenamePublicError(err);
+ errorResponse(res, status, type, error, {
+ handler: 'rename-path',
+ cause: err,
+ });
+ return;
+ }
+
+ if (result.renamedAssets.length > 0) {
+ invalidateReferencedAssetsCache();
+ }
+
+ let summaryResponse: SummaryResponse | undefined;
+ if (result.renamedAssets.length > 0 && result.rewrittenDocs.length > 0) {
+ const subject = `Renamed asset ${fromPath} → ${toPath}`;
+ summaryResponse = attributeRenameWriteToActor(
+ actor,
+ subject,
+ result.rewrittenDocs.map(({ docName }) => ({ docName, subject })),
+ {
+ context: 'handleRenamePath asset branch',
+ onAnonymous: () => {
+ log.debug(
+ {
+ kind: 'asset',
+ fromPath,
+ toPath,
+ affectedDocs: result.rewrittenDocs.length,
+ affectedAssets: result.renamedAssets.length,
+ },
+ '[rename-path] anonymous actor; no contributor recorded (no agentId in body and getPrincipal() returned null)',
+ );
+ },
+ },
+ );
+ }
+ renameAttributionCounter().add(1, {
+ kind: 'rename-asset',
+ attribution_kind: actor.kind,
+ });
+
+ if (flushContributors) {
+ try {
+ await flushContributors();
+ } catch (flushErr) {
+ log.warn(
+ { err: flushErr },
+ '[rename-path] flushContributors failed after asset rename (commitSha backfill may be deferred)',
+ );
+ }
+ }
+
+ successResponse(
+ res,
+ 200,
+ RenamePathSuccessSchema,
+ {
+ renamed: [],
+ renamedAssets: result.renamedAssets,
+ rewrittenDocs: result.rewrittenDocs,
+ ...(summaryResponse ? { summary: summaryResponse } : {}),
+ },
+ { handler: 'rename-path' },
+ );
+ return;
+ }
+ // Register the source's actual on-disk extension before downstream
+ // checks so admission, conflict checks, and existsSync probes all see
+ // the right value when the file watcher hasn't yet observed the source
+ // (boot race).
+ if (operationKind === 'file') {
+ probeAndRegisterSourceFileExtension(contentDir, fromPath);
+ }
+ // Conflict-aware refusal. Renaming a conflicted source doc would
+ // shift the file path while the merge stages still live at the
+ // old path — the disk-watcher → reconcile loop would then see two
+ // paths racing the same content. For a folder rename we ALSO
+ // refuse if any affected child carries 'conflict': the per-doc
+ // rewrite spine (`applyManagedRenameMapToLoadedDocument` →
+ // `composeAndWriteRawBody`) is a sibling primitive to
+ // `applyAgentMarkdownWrite` and does NOT inherit its gate.
+ // Mirrors handleDeletePath's affected-docs scan.
+ //
+ // Dual-source check: hocuspocus.documents.get() returns undefined
+ // for docs evicted from memory (e.g., after boot-time
+ // restoreLifecycleFromConflictsJson disconnects them). Falling back
+ // to ConflictStore via SyncEngine catches that eviction race —
+ // mirrors the dual-source pattern used in handleSyncConflictContent's
+ // 404 gate.
+ // Enumerate from disk (not the lagging file index) so the conflict
+ // pre-check sees every on-disk child of the folder — same root cause
+ // as the spine's `affectedDocNames`.
+ const renameAffectedDocNames =
+ operationKind === 'file'
+ ? [docNameForFileOperationPath(contentDir, fromPath)]
+ : listManagedDocNamesUnderFolderFromDisk(
+ resolveContentEntryPath(contentDir, 'folder', fromPath),
+ );
+ const renameEngine = getSyncEngine?.();
+ const renameTrackedFiles = new Set(
+ renameEngine ? renameEngine.getConflicts().map((c) => c.file) : [],
+ );
+ for (const affected of renameAffectedDocNames) {
+ const affectedDocName = affected;
+ const doc = hocuspocus.documents.get(affectedDocName);
+ const filePath = docNameToRelativePath(affectedDocName);
+ const conflictedByLifecycle = doc !== undefined && isDocInConflict(doc);
+ const conflictedByStore = renameTrackedFiles.has(filePath);
+ if (conflictedByLifecycle || conflictedByStore) {
+ respondDocInConflict(res, new DocInConflictError({ file: filePath }), 'rename-path');
+ return;
+ }
+ }
+
+ if (contentFilter) {
+ // Mirror `resolveContentEntryPath`'s explicit-extension detection so
+ // a destination like `bar.mdx` is checked verbatim instead of as
+ // `bar.mdx.md` (which would miss `*.mdx` exclusion patterns).
+ const sourceExt = isSupportedDocFile(fromPath)
+ ? extname(fromPath)
+ : getDocExtension(fromPath);
+ const excluded =
+ operationKind === 'file'
+ ? contentFilter.isExcluded(
+ isSupportedDocFile(toPath) ? toPath : `${toPath}${sourceExt}`,
+ )
+ : contentFilter.isDirExcluded(toPath);
+ if (excluded) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ `Destination ${operationKind === 'file' ? 'document' : 'folder'} is excluded by the project content config.`,
+ { handler: 'rename-path' },
+ );
+ return;
+ }
+ }
+
+ // Thread the actor identity through to the rewrite spine so the
+ // rename log entry carries the right writerId. Anonymous → service
+ // writer fallback is handled inside the spine.
+ const renameActor =
+ actor.kind === 'agent' || actor.kind === 'principal'
+ ? {
+ writerId: actor.writerId,
+ displayName: actor.displayName,
+ colorSeed: actor.colorSeed,
+ actorMetadata: actor.actor,
+ }
+ : undefined;
+
+ let result: {
+ renamed: RenamedDocMapping[];
+ renamedAssets: RenamedAssetMapping[];
+ rewrittenDocs: ManagedRenameRewrittenDoc[];
+ };
+ try {
+ result = await _performManagedRenameForDocs(
+ fromPath,
+ toPath,
+ operationKind,
+ renameActor ? { actor: renameActor } : {},
+ );
+ } catch (err) {
+ // The spine's own conflict assertions cover a WIDER set than the
+ // pre-check above: backlink-source and asset-referencing docs
+ // rewritten as a side effect of the rename. Mirror the asset
+ // branch so those surface as the documented 409 doc-in-conflict
+ // envelope instead of falling through `toManagedRenamePublicError`
+ // to a generic 500.
+ if (err instanceof DocInConflictError) {
+ respondDocInConflict(res, err, 'rename-path');
+ return;
+ }
+ if (err instanceof ManagedRenameCollisionError) {
+ errorResponse(res, 409, 'urn:ok:error:doc-already-exists', withPeriod(err.message), {
+ handler: 'rename-path',
+ extensions: { colliding: err.colliding },
+ cause: err,
+ });
+ return;
+ }
+ throw err;
+ }
+
+ if (result.renamed.length === 0 && result.renamedAssets.length === 0) {
+ successResponse(
+ res,
+ 200,
+ RenamePathSuccessSchema,
+ { renamed: [], renamedAssets: [], rewrittenDocs: [] },
+ { handler: 'rename-path' },
+ );
+ return;
+ }
+
+ if (result.renamedAssets.length > 0) {
+ invalidateReferencedAssetsCache();
+ }
+
+ let summaryResponse: SummaryResponse | undefined;
+ const logicalRenames = result.renamed.filter(
+ ({ fromDocName, toDocName }) => fromDocName !== toDocName,
+ );
+ if (logicalRenames.length > 0) {
+ summaryResponse = attributeRenameWriteToActor(
+ actor,
+ `Renamed ${fromPath} → ${toPath}`,
+ logicalRenames.map(({ fromDocName, toDocName }) => ({
+ docName: toDocName,
+ subject: formatRenameSubject(fromDocName, toDocName),
+ })),
+ {
+ context: 'handleRenamePath',
+ onAnonymous: () => {
+ log.debug(
+ { kind, fromPath, toPath, affectedDocs: result.renamed.length },
+ '[rename-path] anonymous actor — no contributor recorded (no agentId in body and getPrincipal() returned null)',
+ );
+ },
+ },
+ );
+ }
+ renameAttributionCounter().add(1, {
+ kind: `rename-${operationKind}`,
+ attribution_kind: actor.kind,
+ });
+
+ // Flush pending contributors so the rename-log entry's commitSha is
+ // backfilled by `commitToWipRefInner` BEFORE the API responds.
+ // Without this, a "pure rename without subsequent edit" leaves
+ // commitSha as '' until the next persistence drain (which may never
+ // happen) — the timeline rename-history mitigation depends on
+ // commitSha being a real 40-char SHA at read time. Mirrors the
+ // pattern at handleRollback (post-rollback flushContributors call).
+ if (flushContributors) {
+ try {
+ await flushContributors();
+ } catch (flushErr) {
+ log.warn(
+ { err: flushErr },
+ '[rename-path] flushContributors failed (commitSha backfill may be deferred)',
+ );
+ }
+ }
+
+ successResponse(
+ res,
+ 200,
+ RenamePathSuccessSchema,
+ {
+ renamed: result.renamed,
+ renamedAssets: result.renamedAssets,
+ rewrittenDocs: result.rewrittenDocs,
+ ...(summaryResponse ? { summary: summaryResponse } : {}),
+ },
+ { handler: 'rename-path' },
+ );
+ } catch (e) {
+ const { status, type, error } = toManagedRenamePublicError(e);
+ errorResponse(res, status, type, error, {
+ handler: 'rename-path',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'rename-path', method: 'POST' },
+ );
+
+ const handleDeletePath = withValidation(
+ DeletePathRequestSchema,
+ async (_req, res, body) => {
+ try {
+ extractAgentIdentity(body as unknown as Record<string, unknown>); // attribution threading
+ const { kind, path } = body;
+ if (!isValidRelativeContentPath(path)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'path must be a relative content path.',
+ { handler: 'delete-path' },
+ );
+ return;
+ }
+ const assetResolution =
+ kind === 'asset' ? resolveExtensionlessAssetPath(path) : { path, ambiguous: false };
+ if (assetResolution.ambiguous) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'Asset path without an extension matches multiple files.',
+ { handler: 'delete-path' },
+ );
+ return;
+ }
+ const operationPath = assetResolution.path;
+ const operationKind = kind === 'asset' && isSupportedDocFile(operationPath) ? 'file' : kind;
+ if (operationKind === 'file') {
+ probeAndRegisterSourceFileExtension(contentDir, operationPath);
+ }
+ // The canonical arm is load-bearing HERE above all: delete resolves the
+ // target through a symlinked directory and runs `tracedRmSync(...,
+ // { recursive: true })`, so a lexically-clean `escape-hatch/local` that
+ // realpaths to `.ok/local` would recursively remove server.lock /
+ // principal.json / cache (or `.git/objects`). The lexical check cannot
+ // see through the link; the canonical one can.
+ if (isReservedProjectStatePath(operationPath) || canonicalTargetIsReserved(operationPath)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ '.ok and .git are reserved directories.',
+ { handler: 'delete-path' },
+ );
+ return;
+ }
+
+ const outcome = await fileOpsService.deletePath(operationKind, operationPath);
+ if (!outcome.ok) {
+ if (outcome.kind === 'not-found') {
+ errorResponse(
+ res,
+ 404,
+ 'urn:ok:error:doc-not-found',
+ `${operationKind} does not exist.`,
+ { handler: 'delete-path' },
+ );
+ } else if (outcome.kind === 'type-mismatch') {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ `Target path is not a ${operationKind}.`,
+ { handler: 'delete-path' },
+ );
+ } else {
+ respondDocInConflict(
+ res,
+ new DocInConflictError({ file: outcome.file }),
+ 'delete-path',
+ );
+ }
+ return;
+ }
+ successResponse(
+ res,
+ 200,
+ DeletePathSuccessSchema,
+ { deletedDocNames: outcome.deletedDocNames },
+ { handler: 'delete-path' },
+ );
+ } catch (e) {
+ if (isContainmentRejection(e)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:path-escape',
+ 'path must not escape content directory.',
+ { handler: 'delete-path', cause: e },
+ );
+ return;
+ }
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to delete path.', {
+ handler: 'delete-path',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'delete-path', method: 'POST' },
+ );
+
+ // Two-step Trash flow: the renderer calls
+ // `bridge.shell.trashItem` (Step 1) which moves the file to ~/.Trash via
+ // `shell.trashItem`. On success, the renderer POSTs here (Step 2) to
+ // synchronously cleanup server-side state — close Hocuspocus docs, mark
+ // `recentlyRemovedDocs`, purge the file index, broadcast CC1 files.
+ // Does NOT touch disk (the file is already gone from contentDir).
+ //
+ // Idempotent: if the file-watcher already processed the OS-level deletion
+ // between Step 1 and Step 2, `listAffectedDocNames` returns an empty array
+ // and the handler returns 200 with `deletedDocNames: []` rather than 404 —
+ // the desired end state (gone) is still true.
+ const handleTrashCleanup = withValidation(
+ TrashCleanupRequestSchema,
+ async (_req, res, body) => {
+ return withSpan(
+ 'ok.fs.trash_cleanup',
+ {
+ attributes: {
+ 'ok.cleanup.kind': body.kind,
+ 'ok.cleanup.path': normalizeFsPath(body.path),
+ 'ok.cleanup.path.role': classifyFsPath(body.path),
+ },
+ },
+ async () => {
+ try {
+ const bodyObj = body as unknown as Record<string, unknown>;
+ const actor = extractActorIdentity(bodyObj, getPrincipal);
+ if (actor.kind === 'invalid-summary') {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
+ handler: 'trash-cleanup',
+ });
+ return;
+ }
+ const { kind, path } = body;
+ if (!isValidRelativeContentPath(path)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'path must be a relative content path.',
+ { handler: 'trash-cleanup' },
+ );
+ return;
+ }
+ const operationKind = kind === 'asset' && isSupportedDocFile(path) ? 'file' : kind;
+ const operationDocName = stripDocExtension(path);
+ if (operationKind === 'file') {
+ probeAndRegisterSourceFileExtension(contentDir, path);
+ }
+ // Defense in depth — synthetic docs never reach disk so cleanup
+ // against them is meaningless; mirrors the gate handleDeletePath
+ // implicitly enforces via `resolveContentEntryPath` + existsSync.
+ // Folder kind is checked separately: a `kind: 'folder', path:
+ // '__config__'` payload would otherwise reach listAffectedDocNames
+ // + captureAndCloseDocuments on the synthetic config docs inside
+ // that namespace before the per-doc guard at the recently-removed
+ // loop fires.
+ const isReservedFolder =
+ operationKind === 'folder' && isReservedSyntheticFolderPath(path);
+ if (
+ (operationKind === 'file' &&
+ (isSystemDoc(operationDocName) || isConfigDoc(operationDocName))) ||
+ isReservedFolder ||
+ isReservedProjectStatePath(path)
+ ) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ `'${path}' is a reserved document name.`,
+ { handler: 'trash-cleanup' },
+ );
+ return;
+ }
+ const { deletedDocNames } = await fileOpsService.trashCleanup(
+ operationKind,
+ path,
+ operationDocName,
+ 'handleTrashCleanup',
+ );
+ successResponse(
+ res,
+ 200,
+ TrashCleanupSuccessSchema,
+ { deletedDocNames },
+ { handler: 'trash-cleanup' },
+ );
+ } catch (e) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'Failed to clean up after trash.',
+ {
+ handler: 'trash-cleanup',
+ cause: e,
+ },
+ );
+ }
+ },
+ );
+ },
+ { handler: 'trash-cleanup', method: 'POST' },
+ );
+
+ async function handleUploadAsset(req: IncomingMessage, res: ServerResponse): Promise<void> {
+ if (req.method !== 'POST') {
+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
+ handler: 'upload-asset',
+ extraHeaders: { Allow: 'POST' },
+ });
+ return;
+ }
+
+ let uploadResult: UploadResult | undefined;
+ try {
+ uploadResult = await readUploadBody(req, projectDir ?? contentDir);
+ } catch (e) {
+ // All body-parse failures land as UploadWriteError with a URN-form
+ // reason. Tempfile cleanup is handled inside readUploadBody's error
+ // path. Anonymous emit (no extractAgentIdentity yet) is semantically
+ // OK — no Y.Doc mutation has been attempted.
+ if (e instanceof UploadWriteError) {
+ errorResponse(res, uploadStatusFor(e.reason), e.reason, uploadTitleFor(e.reason), {
+ handler: 'upload-asset',
+ cause: e,
+ });
+ return;
+ }
+ errorResponse(res, 400, 'urn:ok:error:malformed-upload', 'Failed to parse upload.', {
+ handler: 'upload-asset',
+ cause: e,
+ });
+ return;
+ }
+
+ const {
+ filename,
+ tempPath,
+ sha,
+ byteLength,
+ parentDocName: rawParentDocName,
+ placement: rawPlacement,
+ } = uploadResult;
+
+ // Belt-and-braces cleanup: if anything below this point errors or
+ // early-returns, the tempfile must go away. Every early-return path
+ // below that does NOT consume tempPath via linkTempToFinal* runs this.
+ const cleanupTempfile = () => {
+ if (existsSync(tempPath)) {
+ try {
+ unlinkSync(tempPath);
+ } catch {
+ // best-effort; orphan sweep reaps stragglers
+ }
+ }
+ };
+
+ // Validate metadata fields (parentDocName etc.) via the shared
+ // `validateBody` middleware. Body-shape failure emits 400
+ // `urn:ok:error:invalid-request` BEFORE `extractAgentIdentity` runs —
+ // an anonymous response is semantically correct here because no Y.Doc
+ // mutation is attempted. Mirrors `withValidation`'s policy for JSON
+ // handlers.
+ const validated = validateBody(
+ UploadRequestSchema,
+ { parentDocName: rawParentDocName, placement: rawPlacement || undefined },
+ res,
+ {
+ handler: 'upload-asset',
+ },
+ );
+ if (!validated.ok) {
+ cleanupTempfile();
+ return;
+ }
+ const { parentDocName, placement } = validated.value;
+
+ // Identity extracted from query params (multipart body precludes JSON).
+ // Capture agentId / agentName so structured upload logs carry
+ // attribution — mirrors precedent #24/#25 and lets operators trace
+ // unexpected file-creation events back to the originating agent
+ // during incident investigation. Both fields follow bounded shapes
+ // (agentId matches AGENT_ID_RE; agentName is sanitized) so they
+ // remain cardinality-safe for log indexing.
+ //
+ // CRUCIAL: identity extraction must precede every SEMANTIC error
+ // emission below (path-escape, no-file-received, storage-error). Body-
+ // shape errors above (urn:ok:error:invalid-request, urn:ok:error:malformed-upload)
+ // are anonymous because no Y.Doc mutation is attempted. The
+ // attribution-sweep-coverage ordering check enforces this distinction
+ // (precedent #24).
+ const { agentId, agentName } = extractAgentIdentity(
+ Object.fromEntries(new URL(req.url ?? '', 'http://localhost').searchParams.entries()),
+ );
+
+ if (byteLength === 0) {
+ cleanupTempfile();
+ errorResponse(res, 400, 'urn:ok:error:no-file-received', 'No file received.', {
+ handler: 'upload-asset',
+ });
+ return;
+ }
+
+ // Reject path-escape attempts.
+ if (
+ parentDocName.includes('\x00') ||
+ parentDocName.includes('..') ||
+ parentDocName.startsWith('/')
+ ) {
+ cleanupTempfile();
+ errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {
+ handler: 'upload-asset',
+ });
+ return;
+ }
+ // Same lexical precondition as the five sibling file-ops, scoped to the
+ // component the server actually resolves: only `dirname(parentDocName)`
+ // ever reaches `resolveUploadDestDir` — the basename is discarded on every
+ // branch — and on the sidebar external-file-drop path that basename is a
+ // raw OS filename (backslash is a legal filename character on macOS and
+ // Linux), so validating the whole string rejects ordinary drops. The check
+ // is load-bearing for the reserved gate below: `canonicalTargetIsReserved`
+ // swallows a failed resolution to `false`, and `resolveContentEntryPath`
+ // throws on any `.` or empty segment — so without it a `./`-prefixed
+ // parentDocName would skate past the canonical arm. `dirname('alpha')` is
+ // `'.'` (a root-level doc), which the predicate rejects but is fine here.
+ const parentDirComponent = dirname(parentDocName);
+ if (parentDirComponent !== '.' && !isValidRelativeContentPath(parentDirComponent)) {
+ cleanupTempfile();
+ errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {
+ handler: 'upload-asset',
+ });
+ return;
+ }
+ // Reserved-subtree gate, same two arms as the sibling file-ops. `.ok`/
+ // `.git` sit INSIDE the content root, so the escape checks above and the
+ // ones in `storeUpload` all pass for `parentDocName: '.ok/skills/x'` — a
+ // literal path, no symlink needed — and the upload would land agent-loaded
+ // content in `.ok/skills/` with none of the skill-schema validation.
+ // Deliberately blanket: this also refuses upload into the two `.ok/`
+ // subtrees the content filter admits as editable docs (`.ok/skills/**` and
+ // `<folder>/.ok/templates/**`) — asset upload sits on the create side of
+ // the reserved boundary, like create-page. This is a fast fail on the
+ // request field; the authoritative check runs on the resolved destination
+ // inside `storeUpload` (kind `reserved-destination`), which also covers the
+ // configured `attachmentFolderPath` arm the request field never sees.
+ if (
+ isReservedProjectStatePath(parentDocName) ||
+ (parentDirComponent !== '.' && canonicalTargetIsReserved(parentDirComponent))
+ ) {
+ cleanupTempfile();
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ '.ok and .git are reserved directories.',
+ { handler: 'upload-asset' },
+ );
+ return;
+ }
+
+ const outcome = await assetService.storeUpload({
+ tempPath,
+ sha,
+ byteLength,
+ filename,
+ parentDocName,
+ placement,
+ });
+ if (outcome.ok) {
+ log.info(
+ {
+ event: 'upload',
+ endpoint: req.url ?? '/api/upload',
+ agentId,
+ agentName,
+ dedup: outcome.deduped,
+ mime: outcome.mime,
+ size: byteLength,
+ // `destPath` is the contentDir-relative asset path. High-
+ // cardinality by nature — fine as a log field consumed by text-
+ // search / by-incident filtering; NEVER promote it to a metric
+ // label (per-asset label explosion).
+ destPath: outcome.path,
+ httpStatus: 200,
+ },
+ outcome.deduped ? '[upload] dedup hit' : '[upload] write ok',
+ );
+ // RFC 9457 §3 success path: drop the `ok: true` wrapper. Wire shape
+ // is `{ src, path, deduped }`; clients discriminate on HTTP status.
+ successResponse(
+ res,
+ 200,
+ UploadAssetSuccessSchema,
+ { src: outcome.src, path: outcome.path, deduped: outcome.deduped },
+ { handler: 'upload-asset' },
+ );
+ return;
+ }
+ switch (outcome.kind) {
+ case 'config-error':
+ log.error(
+ { err: outcome.cause },
+ '[upload] project config has invalid content.attachmentFolderPath',
+ );
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'Server configuration error: invalid attachment folder path.',
+ { handler: 'upload-asset', cause: outcome.cause },
+ );
+ return;
+ case 'invalid-attachment-folder':
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid attachment folder path.', {
+ handler: 'upload-asset',
+ });
+ return;
+ case 'path-escape':
+ errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {
+ handler: 'upload-asset',
+ ...(outcome.cause === undefined ? {} : { cause: outcome.cause }),
+ });
+ return;
+ case 'reserved-destination':
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ '.ok and .git are reserved directories.',
+ { handler: 'upload-asset' },
+ );
+ return;
+ case 'dest-validation-error':
+ log.error(
+ { err: outcome.cause, destDir: outcome.destDir },
+ '[upload] failed to validate destination directory',
+ );
+ errorResponse(res, 500, 'urn:ok:error:storage-error', 'Storage error.', {
+ handler: 'upload-asset',
+ cause: outcome.cause,
+ });
+ return;
+ case 'mkdir-failed':
+ errorResponse(
+ res,
+ uploadStatusFor(outcome.reason),
+ outcome.reason,
+ uploadTitleFor(outcome.reason),
+ {
+ handler: 'upload-asset',
+ cause: outcome.cause,
+ detail: 'failed to create attachment directory',
+ },
+ );
+ return;
+ case 'write-failed':
+ log.error(
+ {
+ event: 'upload',
+ endpoint: req.url ?? '/api/upload',
+ requestId: getRequestId(req),
+ agentId,
+ agentName,
+ filename: outcome.filename,
+ size: byteLength,
+ reason: outcome.reason,
+ httpStatus: uploadStatusFor(outcome.reason),
+ err: outcome.cause,
+ },
+ '[upload] write failed',
+ );
+ errorResponse(
+ res,
+ uploadStatusFor(outcome.reason),
+ outcome.reason,
+ uploadTitleFor(outcome.reason),
+ { handler: 'upload-asset', cause: outcome.cause },
+ );
+ return;
+ }
+ }
+
+ return createApiRouteGroup(
+ {
+ '/api/create-page': handleCreatePage,
+ '/api/create-folder': handleCreateFolder,
+ '/api/duplicate-path': handleDuplicatePath,
+ '/api/rename-path': handleRenamePath,
+ '/api/delete-path': handleDeletePath,
+ '/api/trash/cleanup': handleTrashCleanup,
+ '/api/upload': handleUploadAsset,
+ },
+ {
+ mutating: [
+ '/api/create-page',
+ '/api/create-folder',
+ '/api/duplicate-path',
+ '/api/rename-path',
+ '/api/delete-path',
+ '/api/trash/cleanup',
+ '/api/upload',
+ ],
+ },
+ );
+}
diff --git a/packages/server/src/http/lint-routes.ts b/packages/server/src/http/lint-routes.ts
index e833f96d3..6d3ebbeb4 100644
--- a/packages/server/src/http/lint-routes.ts
+++ b/packages/server/src/http/lint-routes.ts
@@ -37,9 +37,9 @@ import {
ValidationAuditCountsResponseSchema,
ValidationAuditResponseSchema,
} from '@inkeep/open-knowledge-core';
-import { SymlinkEscapeError } from '../apply-managed-rename.ts';
import type { ContentFilter } from '../content-filter.ts';
import type { DerivedDocumentIndexApiPort } from '../derived-document-index.ts';
+import { isContainmentRejection } from '../fs-safety.ts';
import { AuditSupersededError, auditProject, lintDoc } from '../lint/audit.ts';
import { AuditCache } from '../lint/audit-cache.ts';
import { listProjectSchemaFiles, SCHEMA_LIST_CAP } from '../lint/frontmatter-schemas.ts';
@@ -337,7 +337,7 @@ export function createLintRoutes(deps: LintRouteDeps): LintRoutes {
{ handler: 'lint' },
);
} catch (e) {
- if (e instanceof SymlinkEscapeError) {
+ if (isContainmentRejection(e)) {
errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {
handler: 'lint',
});
diff --git a/packages/server/src/services/assets.ts b/packages/server/src/services/assets.ts
index 037bd648c..a3db170a1 100644
--- a/packages/server/src/services/assets.ts
+++ b/packages/server/src/services/assets.ts
@@ -22,9 +22,15 @@ import {
} from '@inkeep/open-knowledge-core';
import { fileTypeFromBuffer } from 'file-type';
import { toContentRelativePath } from '../asset-references.ts';
+import { isReservedProjectStatePath } from '../content/managed-doc-enum.ts';
import { isWithinContentDir } from '../content-path.ts';
import { sanitizeFilename } from '../filename-sanitize.ts';
-import { assertNoSymlinkEscape, isAlreadyExistsError } from '../fs-safety.ts';
+import {
+ assertNoSymlinkEscape,
+ canonicalRelPathForNewTarget,
+ isAlreadyExistsError,
+ isContainmentRejection,
+} from '../fs-safety.ts';
import { tracedMkdirSync } from '../fs-traced.ts';
import { errnoCode } from '../http/handler-utils.ts';
import { getLogger } from '../logger.ts';
@@ -86,6 +92,7 @@ type StoreUploadOutcome =
| { ok: false; kind: 'invalid-attachment-folder' }
| { ok: false; kind: 'path-escape'; cause?: unknown }
| { ok: false; kind: 'dest-validation-error'; cause: unknown; destDir: string }
+ | { ok: false; kind: 'reserved-destination'; destDir: string }
| { ok: false; kind: 'mkdir-failed'; reason: UploadWriteReason; cause: unknown }
| {
ok: false;
@@ -378,12 +385,33 @@ export function createAssetService(deps: AssetServiceDeps): AssetService {
assertNoSymlinkEscape(destDir, resolvedContentDir);
} catch (err) {
cleanupTempfile();
- const message = err instanceof Error ? err.message : String(err);
- if (message.startsWith('symlink-escape:')) {
+ // Classify through the shared family predicate, not a message sniff, so
+ // this split tracks fs-safety.ts automatically: containment rejections
+ // are the caller's 400; everything else (raw errnos, a missing content
+ // root) is a server-side 500.
+ if (isContainmentRejection(err)) {
return { ok: false, kind: 'path-escape' };
}
return { ok: false, kind: 'dest-validation-error', cause: err, destDir };
}
+ // Reserved-subtree gate on the DESTINATION the write actually lands in.
+ // This is the authoritative check: it sees the resolved `destDir`, so it
+ // covers both request arms at once — a `parentDocName` routed into
+ // `.ok`/`.git` through a symlinked directory, and a configured
+ // `content.attachmentFolderPath` that names a reserved subtree directly
+ // (the schema only rejects NUL/absolute/`..`, so `.ok/...` is a legal
+ // config value; a planted `.ok/config.yml` in a cloned tree chooses it).
+ // The route-level check on the request field is a fast fail, not the
+ // boundary.
+ const canonicalDestRel = canonicalRelPathForNewTarget(
+ destDir,
+ resolvedContentDir,
+ getLogger('upload'),
+ );
+ if (isReservedProjectStatePath(canonicalDestRel)) {
+ cleanupTempfile();
+ return { ok: false, kind: 'reserved-destination', destDir };
+ }
// mkdir -p the destination — bare-name / nested attachmentFolderPath
// values produce directories that may not exist at first upload.
try {
@@ -413,6 +441,13 @@ export function createAssetService(deps: AssetServiceDeps): AssetService {
cleanupTempfile();
return { ok: false, kind: 'path-escape' };
}
+ // Reservedness is re-checked here for the same TOCTOU reason containment
+ // is: a symlink-replace between the pre-mkdir gate and mkdir could route
+ // the realized directory into `.ok`/`.git` without leaving the root.
+ if (isReservedProjectStatePath(toPosix(relative(realContentDir, realDestDir)))) {
+ cleanupTempfile();
+ return { ok: false, kind: 'reserved-destination', destDir };
+ }
} catch (e) {
const code = errnoCode(e);
if (code === 'ENOENT') {
diff --git a/packages/server/src/services/file-ops.ts b/packages/server/src/services/file-ops.ts
index 9ca2e7c1b..578fbd66e 100644
--- a/packages/server/src/services/file-ops.ts
+++ b/packages/server/src/services/file-ops.ts
@@ -36,6 +36,19 @@ import { getLogger } from '../logger.ts';
* and the idempotent fast-path returns an empty list.
*/
+/**
+ * Thrown by the duplicate-name allocators when every `copy` / `copy N` slot
+ * for a source path is taken. Lives here (not in a route file) so both the
+ * extension-side allocators that throw it and the native duplicate-path
+ * handler that `instanceof`-matches it import the same class identity.
+ */
+export class DuplicateNameExhaustedError extends Error {
+ constructor(readonly sourcePath: string) {
+ super(`Could not find an available duplicate name for ${sourcePath}`);
+ this.name = 'DuplicateNameExhaustedError';
+ }
+}
+
type FileOpKind = 'file' | 'folder' | 'asset';
type CreateFolderOutcome = { ok: true } | { ok: false; kind: 'already-exists' };
diff --git a/packages/server/src/symlink-guard.ts b/packages/server/src/symlink-guard.ts
index 09d131d73..55f8b21d6 100644
--- a/packages/server/src/symlink-guard.ts
+++ b/packages/server/src/symlink-guard.ts
@@ -24,6 +24,17 @@
* ENOENT, and a naive climb to the lexical parent would pass it — yet a
* write through that link CREATES the target. The link is resolved
* manually so its destination is checked even when absent.
+ *
+ * Sibling primitive: `canonicalRelPathForNewTarget` in `fs-safety.ts` answers
+ * the same realpath-then-refuse-`.ok`/`.git` question for the HTTP file-ops,
+ * with three deliberate differences — its consumer
+ * `isReservedProjectStatePath` matches `.ok`/`.git` at ANY depth (nested
+ * `<folder>/.ok/` is refused there, first-class here); its ENOENT branch
+ * climbs by `dirname` without the manual dangling-link resolution above; and
+ * a root that cannot be canonicalized falls back to the lexical relative path
+ * there (its caller's lexical check still stands), where
+ * `assertNoSymlinkEscape` throws `ContentRootUnavailableError` for a missing
+ * anchor. Harden one and check whether the other needs the same change.
*/
import { lstatSync, readlinkSync, realpathSync } from 'node:fs';