@taskforcehq/taskforce 0.3.313 → 0.3.315

package/dist/mcp/canonicalAssetHelpers.js

@@ -1,11 +1,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash, randomUUID } from 'node:crypto';
+import { normalizeRelativeStorageKey, resolveExistingStorageKeyFilePathInsideRoot, resolveStorageKeyWritePathInsideRoot } from '../utils/pathSafety.js';
 export function createCanonicalAssetHelpers(deps) {
     const normalizeAttachmentStorageKey = (pathValue, fsPathValue) => {
         const fsPathRaw = String(fsPathValue || '').trim().replace(/\\/g, '/');
         if (fsPathRaw) {
-            return fsPathRaw.replace(/^\.taskforce\//, '').trim() || null;
+            return normalizeRelativeStorageKey(fsPathRaw.replace(/^\.taskforce\//, '').trim());
         }
         const pathRaw = String(pathValue || '').trim();
         if (!pathRaw)
@@ -13,10 +14,18 @@ export function createCanonicalAssetHelpers(deps) {
         if (/^https?:\/\//i.test(pathRaw))
             return pathRaw;
         if (pathRaw.startsWith('/api/taskforce/context/')) {
-            return decodeURIComponent(pathRaw.slice('/api/taskforce/context/'.length)).trim() || null;
+            return normalizeRelativeStorageKey(decodeURIComponent(pathRaw.slice('/api/taskforce/context/'.length)).trim());
         }
         return null;
     };
+    const isSafeCanonicalAssetStorage = (asset) => {
+        if (asset.storageProvider === 'external')
+            return true;
+        return Boolean(normalizeRelativeStorageKey(asset.storageKey));
+    };
+    const resolveCanonicalLocalFilePath = (storageKey) => {
+        return resolveExistingStorageKeyFilePathInsideRoot(deps.basePath, storageKey);
+    };
     const buildSyntheticAttachmentId = (taskId, attachment) => {
         const stableSource = [
             taskId,
@@ -32,14 +41,14 @@ export function createCanonicalAssetHelpers(deps) {
         const assetId = String(attachment.assetId || '').trim();
         if (assetId) {
             const byId = deps.workspaceAssetStore.get(assetId, deps.activeWorkspaceId);
-            if (byId && !byId.deletedAt)
+            if (byId && !byId.deletedAt && isSafeCanonicalAssetStorage(byId))
                 return byId;
         }
         const storageKey = normalizeAttachmentStorageKey(attachment.path, attachment.fsPath);
         if (!storageKey || /^https?:\/\//i.test(storageKey))
             return null;
         const byStorageKey = deps.workspaceAssetStore.getByStorageKey(storageKey, deps.activeWorkspaceId);
-        if (byStorageKey && !byStorageKey.deletedAt)
+        if (byStorageKey && !byStorageKey.deletedAt && isSafeCanonicalAssetStorage(byStorageKey))
             return byStorageKey;
         return null;
     };
@@ -80,6 +89,9 @@ export function createCanonicalAssetHelpers(deps) {
             throw new Error('Attachment scan pending');
         }
         if (asset.storageProvider === 'r2') {
+            if (!normalizeRelativeStorageKey(asset.storageKey)) {
+                throw new Error(`Attachment ${attachment.attachmentId} not found on ${targetLabel} ${taskId}`);
+            }
             const attachmentContext = describeAttachmentStorageContext(attachment, asset.storageKey);
             if (!deps.objectStorageClient) {
                 throw new Error(`Attachment read failed from R2 because object storage is not configured in this MCP runtime (${attachmentContext})`);
@@ -97,11 +109,8 @@ export function createCanonicalAssetHelpers(deps) {
             }
             return object.body;
         }
-        const resolvedPath = path.resolve(deps.basePath, asset.storageKey);
-        if (!resolvedPath.startsWith(path.resolve(deps.basePath))) {
-            throw new Error(`Attachment ${attachment.attachmentId} not found on ${targetLabel} ${taskId}`);
-        }
-        if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isFile()) {
+        const resolvedPath = resolveCanonicalLocalFilePath(asset.storageKey);
+        if (!resolvedPath) {
             throw new Error(`Attachment ${attachment.attachmentId} not found on ${targetLabel} ${taskId}`);
         }
         return fs.readFileSync(resolvedPath);
@@ -117,6 +126,9 @@ export function createCanonicalAssetHelpers(deps) {
             throw new Error('Document scan pending');
         }
         if (asset.storageProvider === 'r2') {
+            if (!normalizeRelativeStorageKey(asset.storageKey)) {
+                throw new Error(`Document ${asset.assetId} not found in workspace ${deps.activeWorkspaceId}.`);
+            }
             if (!deps.objectStorageClient) {
                 throw new Error(`Document read failed from R2 because object storage is not configured in this MCP runtime (assetId=${asset.assetId}, storageKey=${asset.storageKey || 'unknown'})`);
             }
@@ -133,11 +145,8 @@ export function createCanonicalAssetHelpers(deps) {
             }
             return object.body;
         }
-        const resolvedPath = path.resolve(deps.basePath, asset.storageKey);
-        if (!resolvedPath.startsWith(path.resolve(deps.basePath))) {
-            throw new Error(`Document ${asset.assetId} not found in workspace ${deps.activeWorkspaceId}.`);
-        }
-        if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isFile()) {
+        const resolvedPath = resolveCanonicalLocalFilePath(asset.storageKey);
+        if (!resolvedPath) {
             throw new Error(`Document ${asset.assetId} not found in workspace ${deps.activeWorkspaceId}.`);
         }
         return fs.readFileSync(resolvedPath);
@@ -176,14 +185,17 @@ export function createCanonicalAssetHelpers(deps) {
             const logicalFilename = resolveAttachmentLogicalFilename(attachment, asset);
             if (logicalFilename !== requestedFilename)
                 continue;
-            const relativePath = deps.toPosixPath(path.relative(deps.projectRoot, path.resolve(deps.basePath, asset.storageKey)));
+            const absolutePath = resolveStorageKeyWritePathInsideRoot(deps.basePath, asset.storageKey);
+            if (!absolutePath)
+                continue;
+            const relativePath = deps.toPosixPath(path.relative(deps.projectRoot, absolutePath));
             return {
                 index,
                 attachment,
                 asset,
                 descriptor,
                 relativePath,
-                absolutePath: path.resolve(deps.basePath, asset.storageKey),
+                absolutePath,
                 logicalFilename,
             };
         }
@@ -197,10 +209,12 @@ export function createCanonicalAssetHelpers(deps) {
         const targetId = String(targetIdRaw || '').trim();
         if (!relativePath || !targetId)
             return null;
-        const absolutePath = path.resolve(deps.projectRoot, relativePath);
-        if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile())
+        const storageKey = normalizeRelativeStorageKey(relativePath.replace(/^\.taskforce\//, '').trim() || relativePath);
+        if (!storageKey)
+            return null;
+        const absolutePath = resolveExistingStorageKeyFilePathInsideRoot(deps.basePath, storageKey);
+        if (!absolutePath)
             return null;
-        const storageKey = relativePath.replace(/^\.taskforce\//, '').trim() || relativePath;
         const buffer = fs.readFileSync(absolutePath);
         const stats = fs.statSync(absolutePath);
         const mimeType = deps.inferMimeTypeFromPath(relativePath);

package/dist/mcp/documentAssetRegistrar.js

@@ -72,13 +72,13 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('save_workstream_attachment', (context) => ({
-        description: context.describeTool('Save a file and attach it to a workstream. Use this for generated content or existing files from disk. Set overwrite=true to replace an existing canonical attachment with the same filename.'),
+        description: context.describeTool('Save a file and attach it to a workstream. Use this for generated content or existing local files from disk. In cloud MCP, use inline content instead of server-local file paths. Set overwrite=true to replace an existing canonical attachment with the same filename.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
                 filename: stringProperty('Destination filename for the attachment.'),
                 content: stringProperty('Inline file content; use this for AI-authored markdown/text attachments.'),
-                sourcePath: stringProperty('Path to an existing source file. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
+                sourcePath: stringProperty('Path to an existing source file for local runtimes only. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
                 caption: stringProperty('Optional attachment caption.'),
                 overwrite: booleanProperty('When true, overwrite an existing canonical workstream attachment with the same filename instead of creating a new one.'),
             },
@@ -117,13 +117,13 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('save_initiative_attachment', (context) => ({
-        description: context.describeTool('Save a file and attach it to an initiative. Use this for generated content or existing files from disk. Set overwrite=true to replace an existing canonical attachment with the same filename.'),
+        description: context.describeTool('Save a file and attach it to an initiative. Use this for generated content or existing local files from disk. In cloud MCP, use inline content instead of server-local file paths. Set overwrite=true to replace an existing canonical attachment with the same filename.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
                 filename: stringProperty('Destination filename for the attachment.'),
                 content: stringProperty('Inline file content; use this for AI-authored markdown/text attachments.'),
-                sourcePath: stringProperty('Path to an existing source file. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
+                sourcePath: stringProperty('Path to an existing source file for local runtimes only. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
                 caption: stringProperty('Optional attachment caption.'),
                 overwrite: booleanProperty('When true, overwrite an existing canonical initiative attachment with the same filename instead of creating a new one.'),
             },
@@ -422,13 +422,13 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('save_task_attachment', (context) => ({
-        description: context.describeTool('Save a file and attach it to a task. Use this for generated content, existing files from disk, or staged remote uploads for binary files in cloud MCP. Set overwrite=true to replace an existing canonical attachment with the same filename. For AI-authored markdown/text, use inline content for AI-authored markdown/text rather than writing an external temp file first.'),
+        description: context.describeTool('Save a file and attach it to a task. Use this for generated content, existing local files from disk, or staged remote uploads for binary files in cloud MCP. In cloud MCP, use inline content or the staged upload flow instead of server-local file paths. Set overwrite=true to replace an existing canonical attachment with the same filename. For AI-authored markdown/text, use inline content for AI-authored markdown/text rather than writing an external temp file first.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
                 filename: stringProperty('Destination filename for the attachment.'),
                 content: stringProperty('Inline file content; use this for AI-authored markdown/text attachments.'),
-                sourcePath: stringProperty('Path to an existing source file. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
+                sourcePath: stringProperty('Path to an existing source file for local runtimes only. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
                 uploadedPath: stringProperty('Finalize a previously staged remote upload by passing the uploaded Taskforce storage path returned by save_task_attachment init mode.'),
                 uploadDraftId: stringProperty('Finalize a previously staged remote upload by passing the uploadDraftId returned by save_task_attachment init mode.'),
                 mimeType: stringProperty('Mime type for staged remote uploads such as image/png or image/jpeg. Provide this with sizeBytes to start a staged upload.'),

package/dist/mcp/runtime.js

@@ -11,6 +11,7 @@ import { buildResolveAiProfileInputFromBootstrap } from './aiProfileBootstrap.js
 import { createCanonicalAssetHelpers } from './canonicalAssetHelpers.js';
 import { createDocumentHelpers } from './documentHelpers.js';
 import { createTaskAttachmentHelpers } from './taskAttachmentHelpers.js';
+import { isPathWithinRoot } from '../utils/pathContainment.js';
 import { validateStructuredDocForAttach } from './structuredDocValidation.js';
 import { validateStructuredCommentForAdd } from './structuredCommentValidation.js';
 import { resolveDatabaseConfigFromEnv } from '../storage/providerConfig.js';
@@ -23,6 +24,7 @@ import { getDocumentReferenceLabel, parseDocumentReference } from '../utils/docu
 import { getImageReferenceLabel, parseImageReference } from '../utils/imageReferences.js';
 import { inferCanonicalAssetKind, isValidCanonicalDocumentAsset } from '../utils/canonicalAssetKind.js';
 import { getTaskReferenceLabel, shouldUseProvisionalTaskReferences } from '../utils/taskReferences.js';
+import { resolveStorageKeyPathInsideRoot } from '../utils/pathSafety.js';
 import { parseAiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
 import { parseAiProfileSeatScope } from '../shared/aiProfileSeatScope.js';
 import { formatInitiativeReference, formatWorkstreamReference, resolveInitiativeReference, parseWorkstreamReference, } from '../utils/planningReferences.js';
@@ -75,6 +77,7 @@ const TOOL_LOG_TRUNCATED_DEPTH_VALUE = '[truncated-depth]';
 const TOOL_LOG_MAX_STRING_LENGTH = 160;
 const TOOL_LOG_MAX_ARRAY_ITEMS = 8;
 const toolLogSensitiveWordSet = new Set(['token', 'tokens', 'password', 'passwords', 'secret', 'secrets', 'authorization']);
+const toolLogSensitiveWordPairs = new Set(['api:key', 'client:secret', 'bearer:token', 'proxy:authorization', 'private:key']);
 function truncateToolLogString(value) {
     return `${value.slice(0, TOOL_LOG_MAX_STRING_LENGTH)}${value.length > TOOL_LOG_MAX_STRING_LENGTH ? '…' : ''}`;
 }
@@ -88,6 +91,10 @@ function shouldRedactToolLogKey(key) {
         return false;
     if (words.some((word) => toolLogSensitiveWordSet.has(word)))
         return true;
+    for (let index = 0; index < words.length - 1; index += 1) {
+        if (toolLogSensitiveWordPairs.has(`${words[index]}:${words[index + 1]}`))
+            return true;
+    }
     const compact = words.join('');
     return compact === 'apikey'
         || compact === 'clientsecret'
@@ -124,11 +131,29 @@ function sanitizeToolArgsForLog(args) {
     };
     return visit(args, 0);
 }
+function redactRecoverableErrorDetails(details) {
+    const visit = (value, key) => {
+        if (key && shouldRedactToolLogKey(key))
+            return TOOL_LOG_REDACTED_VALUE;
+        if (value === null || value === undefined)
+            return value;
+        if (Array.isArray(value))
+            return value.map((item) => visit(item));
+        if (typeof value !== 'object')
+            return value;
+        const output = {};
+        for (const [childKey, childValue] of Object.entries(value)) {
+            output[childKey] = visit(childValue, childKey);
+        }
+        return output;
+    };
+    return visit(details);
+}
 function resolveRecoverableToolError(error) {
     const message = error instanceof Error ? String(error.message || '').trim() : '';
     const code = error instanceof TaskforceRuleError ? error.code : undefined;
     const statusCode = error instanceof TaskforceRuleError ? error.statusCode : undefined;
-    const details = error instanceof TaskforceRuleError ? error.details : undefined;
+    const details = error instanceof TaskforceRuleError ? redactRecoverableErrorDetails(error.details) : undefined;
     if (/^This tool requires an AI profile\./i.test(message)) {
         return {
             message,
@@ -914,7 +939,6 @@ export function createTaskforceMcpServer(options = {}) {
         throw new TaskforceRuleError(`AI profile "${profile.name}" has been retired from this workspace. Call resolve_profile to reactivate it before retrying.`, 409, 'AI_PROFILE_RETIRED', {
             workspaceId: ACTIVE_WORKSPACE_ID,
             profileId: profile.id,
-            profileToken: profile.profileToken || null,
             archivedReason: profile.archivedReason || null,
         });
     }
@@ -1404,12 +1428,8 @@ export function createTaskforceMcpServer(options = {}) {
     function isHttpUrl(value) {
         return /^https?:\/\//i.test(value);
     }
-    function isWithinRoot(filePath, root) {
-        const relative = path.relative(root, filePath);
-        return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
-    }
     function isApprovedAttachmentSourcePath(filePath, projectRootReal) {
-        return getApprovedAttachmentSourceRoots(projectRootReal).some((root) => isWithinRoot(filePath, root));
+        return getApprovedAttachmentSourceRoots(projectRootReal).some((root) => isPathWithinRoot(filePath, root));
     }
     function toPosixPath(filePath) {
         return filePath.split(path.sep).join('/');
@@ -1842,7 +1862,31 @@ export function createTaskforceMcpServer(options = {}) {
             },
         };
     }
+    function buildPlanningWriteResponseDeferredDetails(targetType, entity, context) {
+        const referenceLabel = targetType === 'initiative'
+            ? (typeof entity?.referenceLabel === 'string' ? entity.referenceLabel : formatInitiativeReference(entity))
+            : (typeof entity?.referenceLabel === 'string' ? entity.referenceLabel : formatWorkstreamReference(entity));
+        return {
+            deferred: true,
+            reason: 'cloud_write_fast_ack',
+            message: 'The write completed. Taskforce skipped richer response hydration on the cloud MCP write path to avoid turning committed writes into client-visible timeouts under concurrent QA load.',
+            nextTool: targetType === 'initiative' ? 'get_initiative' : 'get_workstream',
+            suggestedArgs: {
+                id: referenceLabel || entity?.id || '',
+            },
+            context,
+        };
+    }
     function buildPostWriteInitiativeResourcePayload(initiative, context) {
+        if (runtimeMode === 'cloud') {
+            return {
+                initiative: buildPlanningInitiativeSummary(initiative),
+                workstreamCount: 0,
+                taskCount: 0,
+                workstreams: [],
+                responseHydration: buildPlanningWriteResponseDeferredDetails('initiative', initiative, context),
+            };
+        }
         try {
             return buildInitiativeResourcePayload(initiative);
         }
@@ -1857,6 +1901,14 @@ export function createTaskforceMcpServer(options = {}) {
         }
     }
     function buildPostWriteWorkstreamResourcePayload(workstream, context) {
+        if (runtimeMode === 'cloud') {
+            return {
+                workstream: buildPlanningWorkstreamSummary(workstream),
+                taskCount: 0,
+                tasks: [],
+                responseHydration: buildPlanningWriteResponseDeferredDetails('workstream', workstream, context),
+            };
+        }
         try {
             return buildWorkstreamResourcePayload(workstream);
         }
@@ -2291,6 +2343,9 @@ export function createTaskforceMcpServer(options = {}) {
         if (hasContent === hasSourcePath) {
             throw new Error("Provide exactly one of: content or sourcePath");
         }
+        if (hasSourcePath && runtimeMode === 'cloud') {
+            throw new Error('sourcePath is only available in local runtimes. In cloud runtime, provide content instead.');
+        }
         const now = new Date().toISOString();
         const safeCaption = typeof caption === 'string' && caption.trim().length > 0
             ? caption.trim()
@@ -2919,9 +2974,24 @@ export function createTaskforceMcpServer(options = {}) {
             case "replace_task_checklist": {
                 const { taskId, items } = args;
                 const { id: resolvedTaskId } = resolveTaskByIdentifierOrThrow(taskId);
+                const now = new Date().toISOString();
+                const checklistItems = Array.isArray(items)
+                    ? items.map((item, index) => ({
+                        id: item?.id,
+                        taskId: resolvedTaskId,
+                        title: String(item?.title ?? item?.text ?? '').trim() || `Checklist item ${index + 1}`,
+                        isCompleted: Boolean(item?.isCompleted ?? item?.done),
+                        order: Number.isFinite(Number(item?.order)) ? Number(item.order) : index,
+                        createdAt: String(item?.createdAt || now),
+                        updatedAt: item?.updatedAt ? String(item.updatedAt) : now,
+                    }))
+                    : [];
                 const updatedTask = core.updateTask(resolvedTaskId, {
-                    checklistItems: Array.isArray(items) ? items : [],
+                    checklistItems,
                 }, ACTIVE_WORKSPACE_ID, { actorRef: getActiveMcpActorRef() });
+                if (!updatedTask) {
+                    throw new Error(`Task ${resolvedTaskId} not found`);
+                }
                 const replaced = core.listChecklistItems(resolvedTaskId, ACTIVE_WORKSPACE_ID);
                 recordMcpWriteAudit('replace_task_checklist', {
                     taskId: resolvedTaskId,
@@ -2937,7 +3007,6 @@ export function createTaskforceMcpServer(options = {}) {
                             text: JSON.stringify({
                                 taskId: resolvedTaskId,
                                 items: replaced,
-                                ...(updatedTask ? { task: updatedTask } : {}),
                             }, null, 2),
                         }],
                 };
@@ -4496,6 +4565,9 @@ export function createTaskforceMcpServer(options = {}) {
                 const hasContent = typeof content === 'string';
                 const hasSourcePath = typeof sourcePath === 'string' && sourcePath.trim().length > 0;
                 const hasUploadedPath = typeof uploadedPath === 'string' && uploadedPath.trim().length > 0;
+                if (hasSourcePath && runtimeMode === 'cloud') {
+                    throw new Error('sourcePath is only available in local runtimes. In cloud runtime, use content or the staged upload flow instead.');
+                }
                 const contentModeCount = Number(hasContent) + Number(hasSourcePath) + Number(hasUploadedPath);
                 const now = new Date().toISOString();
                 const safeCaption = typeof caption === 'string' && caption.trim().length > 0
@@ -4820,8 +4892,8 @@ export function createTaskforceMcpServer(options = {}) {
                             await objectStorageClient.deleteObject(replacedStorageKey).catch(() => { });
                         }
                         else if (overwriteTarget.asset.storageProvider === 'local') {
-                            const replacedAbsolutePath = path.resolve(basePath, replacedStorageKey);
-                            if (replacedAbsolutePath.startsWith(path.resolve(basePath)) && fs.existsSync(replacedAbsolutePath)) {
+                            const replacedAbsolutePath = resolveStorageKeyPathInsideRoot(basePath, replacedStorageKey);
+                            if (replacedAbsolutePath && fs.existsSync(replacedAbsolutePath)) {
                                 fs.rmSync(replacedAbsolutePath, { force: true });
                             }
                         }

package/dist/mcp/taskAttachmentHelpers.js

@@ -1,18 +1,40 @@
 export function createTaskAttachmentHelpers(deps) {
     const isCanonicalDocumentAssetRecord = (asset) => deps.isValidCanonicalDocumentAsset(asset);
+    const inferSpecificMimeType = (...candidates) => {
+        for (const candidate of candidates) {
+            const value = String(candidate || '').trim();
+            if (!value)
+                continue;
+            const inferred = deps.inferMimeTypeFromPath(value);
+            if (inferred && inferred !== 'application/octet-stream')
+                return inferred;
+        }
+        return '';
+    };
     const describeTaskAttachment = (taskId, attachmentInput) => {
         const attachment = deps.canonicalAssetHelpers.toTaskAttachmentRecord(attachmentInput);
         const asset = deps.canonicalAssetHelpers.getAttachmentAssetRecord(attachment);
         const storageKey = deps.canonicalAssetHelpers.normalizeAttachmentStorageKey(attachment.path, attachment.fsPath);
-        const assetId = String(attachment.assetId || asset?.assetId || '').trim() || undefined;
-        const source = (asset?.storageProvider === 'external' || /^https?:\/\//i.test(String(attachment.path || '').trim()))
+        const assetId = String(asset?.assetId || '').trim() || undefined;
+        const source = (asset?.storageProvider === 'external'
+            || /^https?:\/\//i.test(String(attachment.path || '').trim())
+            || (!asset && !storageKey))
             ? 'external'
             : 'canonical';
-        const mimeType = String(asset?.mimeType
-            || (storageKey && !/^https?:\/\//i.test(storageKey) ? deps.inferMimeTypeFromPath(storageKey) : '')
-            || deps.inferMimeTypeFromPath(String(attachment.originalFilename || attachment.displayName || attachment.caption || attachment.path || ''))).trim() || 'application/octet-stream';
-        const kind = asset?.kind || deps.inferAssetKind(storageKey || String(attachment.path || ''), mimeType);
-        const isCanonicalDocument = Boolean(asset && isCanonicalDocumentAssetRecord(asset)) || (!asset && kind === 'document');
+        const storedMimeType = String(asset?.mimeType || '').trim();
+        const inferredMimeType = inferSpecificMimeType(asset?.originalFilename, asset?.storageKey, storageKey && !/^https?:\/\//i.test(storageKey) ? storageKey : '', attachment.originalFilename, attachment.displayName, attachment.path);
+        const mimeType = (storedMimeType && storedMimeType !== 'application/octet-stream'
+            ? storedMimeType
+            : inferredMimeType) || storedMimeType || 'application/octet-stream';
+        const inferredKind = deps.inferAssetKind(asset?.originalFilename || asset?.storageKey || storageKey || String(attachment.originalFilename || attachment.path || ''), mimeType);
+        const kind = asset?.kind && asset.kind !== 'file' ? asset.kind : inferredKind;
+        const isCanonicalDocument = kind === 'document' && (!asset
+            || isCanonicalDocumentAssetRecord({
+                kind,
+                storageKey: String(asset.storageKey || storageKey || '').trim(),
+                originalFilename: String(asset.originalFilename || attachment.originalFilename || '').trim(),
+                mimeType,
+            }));
         const referenceNumber = typeof attachment.referenceNumber === 'number'
             ? attachment.referenceNumber
             : (typeof asset?.referenceNumber === 'number' ? asset.referenceNumber : null);

package/dist/migrations/taskSchemaMigrations.js

@@ -700,6 +700,7 @@ export function ensureEntitlementsSchema(db) {
             label TEXT,
             description TEXT,
             is_custom INTEGER NOT NULL DEFAULT 0,
+            public_visible INTEGER,
             public_label TEXT,
             public_description TEXT,
             public_description_visible INTEGER,
@@ -773,6 +774,9 @@ export function ensureEntitlementsSchema(db) {
     if (!planFeatureCatalogOverrideColumns.some((column) => column.name === 'is_custom')) {
         db.exec(`ALTER TABLE plan_feature_catalog_overrides ADD COLUMN is_custom INTEGER NOT NULL DEFAULT 0`);
     }
+    if (!planFeatureCatalogOverrideColumns.some((column) => column.name === 'public_visible')) {
+        db.exec(`ALTER TABLE plan_feature_catalog_overrides ADD COLUMN public_visible INTEGER`);
+    }
     if (!planFeatureCatalogOverrideColumns.some((column) => column.name === 'public_description_visible')) {
         db.exec(`ALTER TABLE plan_feature_catalog_overrides ADD COLUMN public_description_visible INTEGER`);
     }

package/dist/server/index.js

@@ -784,7 +784,7 @@ export function createStandaloneServer(options) {
                         return;
                     }
                 }
-                if (isAuthApiPath) {
+                if (shouldApplyAuthRateLimit) {
                     const latestAuthRateSettings = resolveAuthRateLimitSettings();
                     if (latestAuthRateSettings.enabled !== authRateLimitSettings.enabled
                         || latestAuthRateSettings.maxRequests !== authRateLimitSettings.maxRequests

package/dist/server/routes/admin.js

@@ -732,6 +732,9 @@ export function registerAdminRoutes(deps) {
         const publicDescription = body?.publicDescription === undefined || body?.publicDescription === null
             ? body?.publicDescription
             : String(body.publicDescription);
+        const publicVisible = body?.publicVisible === undefined || body?.publicVisible === null
+            ? body?.publicVisible
+            : (body.publicVisible === false ? false : true);
         const publicDescriptionVisible = body?.publicDescriptionVisible === undefined || body?.publicDescriptionVisible === null
             ? body?.publicDescriptionVisible
             : (body.publicDescriptionVisible === false ? false : true);
@@ -772,6 +775,7 @@ export function registerAdminRoutes(deps) {
             const feature = core.createCustomPlanFeatureCatalogEntry({
                 label,
                 description,
+                publicVisible,
                 publicLabel,
                 publicDescription,
                 publicDescriptionVisible,
@@ -781,6 +785,7 @@ export function registerAdminRoutes(deps) {
                 featureKey: feature.featureKey,
                 label: feature.label,
                 description: feature.description,
+                publicVisible: feature.publicVisible ?? null,
                 publicLabel: feature.publicLabel ?? null,
                 publicDescription: feature.publicDescription ?? null,
                 publicDescriptionVisible: feature.publicDescriptionVisible ?? null,
@@ -817,6 +822,9 @@ export function registerAdminRoutes(deps) {
         const publicDescription = body?.publicDescription === undefined || body?.publicDescription === null
             ? body?.publicDescription
             : String(body.publicDescription);
+        const publicVisible = body?.publicVisible === undefined || body?.publicVisible === null
+            ? body?.publicVisible
+            : (body.publicVisible === false ? false : true);
         const publicDescriptionVisible = body?.publicDescriptionVisible === undefined || body?.publicDescriptionVisible === null
             ? body?.publicDescriptionVisible
             : (body.publicDescriptionVisible === false ? false : true);
@@ -853,6 +861,7 @@ export function registerAdminRoutes(deps) {
                 featureKey,
                 label,
                 description,
+                publicVisible,
                 publicLabel,
                 publicDescription,
                 publicDescriptionVisible,
@@ -862,6 +871,7 @@ export function registerAdminRoutes(deps) {
                 featureKey,
                 label: feature.label,
                 description: feature.description,
+                publicVisible: feature.publicVisible ?? null,
                 publicLabel: feature.publicLabel ?? null,
                 publicDescription: feature.publicDescription ?? null,
                 publicDescriptionVisible: feature.publicDescriptionVisible ?? null,

package/dist/server/routes/billing.js

@@ -2669,6 +2669,9 @@ export function registerBillingRoutes(deps) {
                             return acc;
                         }
                         const catalogEntry = featureCatalogByKey.get(featureKey);
+                        if (catalogEntry?.publicVisible === false) {
+                            return acc;
+                        }
                         acc.push({
                             featureKey,
                             access,

package/dist/server/routes/documents.js

@@ -25,6 +25,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { normalizeTaskDataRelativePath } from '../../storage/objectStorageClient.js';
+import { resolveExistingStorageKeyFilePathInsideRoot } from '../../utils/pathSafety.js';
 import { shouldUseProvisionalTaskReferences } from '../../utils/taskReferences.js';
 import { purgeExpiredDocuments } from '../../storage/documentPurge.js';
 import { parsePlan } from '../../utils/planParser.js';
@@ -427,7 +428,7 @@ export function registerDocumentRoutes(deps) {
             return;
         }
         const filePath = normalizedRelative
-            ? ensureWithinDir(path.join(basePath, normalizedRelative), basePath)
+            ? resolveExistingStorageKeyFilePathInsideRoot(basePath, normalizedRelative)
             : null;
         const ext = normalizedRelative ? path.extname(normalizedRelative).toLowerCase() : '';
         const resolvedDownloadNameBase = sanitizeDownloadFilename(requestedFilename

package/dist/server/routes.js

@@ -23,6 +23,7 @@ import { getDocumentReferenceLabel } from '../utils/documentReferences.js';
 import { getImageReferenceLabel } from '../utils/imageReferences.js';
 import { inferCanonicalAssetKind, isValidCanonicalDocumentAsset } from '../utils/canonicalAssetKind.js';
 import { isReservedWorkspaceId } from '../utils/workspaceIdentity.js';
+import { normalizeRelativeStorageKey, resolveExistingStorageKeyFilePathInsideRoot } from '../utils/pathSafety.js';
 import { resolveVirusScanConfigFromEnv, scanBufferForThreats } from '../security/virusScan.js';
 import { registerSyncRoutes } from './routes/sync.js';
 import { registerBillingRoutes } from './routes/billing.js';
@@ -788,11 +789,14 @@ export function createRoutes(core, context = {}) {
         const resolvedObjectStorage = resolveEffectiveObjectStorageConfig();
         const objectStorageClient = getObjectStorageClient();
         const { basePath } = core.getPaths();
-        const ext = path.extname(params.asset.storageKey).toLowerCase();
+        const storageKey = normalizeRelativeStorageKey(params.asset.storageKey);
+        if (!storageKey)
+            return { statusCode: 404 };
+        const ext = path.extname(storageKey).toLowerCase();
         const resolvedDownloadNameBase = sanitizeDownloadFilename(String(params.requestedFilename || '').trim()
             || params.asset.logicalName
             || params.asset.originalFilename
-            || path.basename(params.asset.storageKey, ext)
+            || path.basename(storageKey, ext)
             || 'download');
         const resolvedDownloadName = ext && !resolvedDownloadNameBase.toLowerCase().endsWith(ext)
             ? `${resolvedDownloadNameBase}${ext}`
@@ -805,7 +809,7 @@ export function createRoutes(core, context = {}) {
                 return { statusCode: 404 };
             }
             if (!params.forceDownload) {
-                const object = await objectStorageClient.getObject(params.asset.storageKey);
+                const object = await objectStorageClient.getObject(storageKey);
                 if (!object) {
                     return { statusCode: 404 };
                 }
@@ -821,15 +825,15 @@ export function createRoutes(core, context = {}) {
             return {
                 statusCode: 302,
                 headers: {
-                    Location: objectStorageClient.createSignedGetUrl(params.asset.storageKey, resolvedObjectStorage.r2.signedDownloadTtlSeconds, { responseContentDisposition: contentDisposition })
+                    Location: objectStorageClient.createSignedGetUrl(storageKey, resolvedObjectStorage.r2.signedDownloadTtlSeconds, { responseContentDisposition: contentDisposition })
                 }
             };
         };
         if (params.asset.storageProvider === 'r2' && objectStorageClient && resolvedObjectStorage.provider === 'r2' && resolvedObjectStorage.r2) {
             return readFromObjectStorage();
         }
-        const filePath = ensureWithinDir(path.join(basePath, params.asset.storageKey), basePath);
-        if (filePath && fs.existsSync(filePath)) {
+        const filePath = resolveExistingStorageKeyFilePathInsideRoot(basePath, storageKey);
+        if (filePath) {
             return {
                 statusCode: 200,
                 headers: {

package/dist/storage/documentIntegrity.js

@@ -2,12 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { DocumentRegistry, createDocumentHash } from './documentRegistry.js';
 import { ObjectStorageClient } from './objectStorageClient.js';
-function isPathInsideRoot(candidatePath, rootDir) {
-    const resolved = path.resolve(candidatePath);
-    const root = path.resolve(rootDir);
-    const relative = path.relative(root, resolved);
-    return !relative.startsWith('..') && !path.isAbsolute(relative);
-}
+import { isPathInsideRoot } from '../utils/pathSafety.js';
 function inc(byCode, code) {
     byCode[code] = (byCode[code] || 0) + 1;
 }