Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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, patconst 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): strinfunction 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 beendiff --git a/packages/server/src/content/managed-doc-enum.ts b/packages/server/src/content/managed-doc-enum.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 typediff --git a/packages/server/src/http/file-ops-routes.test.ts b/packages/server/src/http/file-ops-routes.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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';