collabmd 0.1.43 → 0.1.45

package/src/server/infrastructure/github/github-app-client.js

@@ -1,16 +1,11 @@
 import { createSign } from 'node:crypto';
 
+import { createRequestError } from '../http/http-errors.js';
+
 function base64UrlJson(value) {
   return Buffer.from(JSON.stringify(value)).toString('base64url');
 }
 
-function createRequestError(statusCode, message, code) {
-  const error = new Error(message);
-  error.statusCode = statusCode;
-  error.code = code;
-  return error;
-}
-
 function normalizeBaseUrl(value) {
   return String(value ?? 'https://api.github.com').trim().replace(/\/+$/u, '') || 'https://api.github.com';
 }
@@ -80,7 +75,9 @@ export class GitHubAppClient {
 
   createAppJwt() {
     if (!this.isConfigured()) {
-      throw createRequestError(503, 'GitHub App setup is not configured.', 'HOSTED_GITHUB_APP_NOT_CONFIGURED');
+      throw createRequestError(503, 'GitHub App setup is not configured.', {
+        code: 'HOSTED_GITHUB_APP_NOT_CONFIGURED',
+      });
     }
 
     return createGitHubAppJwt({
@@ -91,7 +88,9 @@ export class GitHubAppClient {
 
   createInstallationSetupUrl({ state } = {}) {
     if (!this.appSlug) {
-      throw createRequestError(503, 'GitHub App slug is not configured.', 'HOSTED_GITHUB_APP_NOT_CONFIGURED');
+      throw createRequestError(503, 'GitHub App slug is not configured.', {
+        code: 'HOSTED_GITHUB_APP_NOT_CONFIGURED',
+      });
     }
 
     const setupUrl = new URL(`/apps/${encodeURIComponent(this.appSlug)}/installations/new`, this.htmlBaseUrl);
@@ -131,7 +130,7 @@ export class GitHubAppClient {
       throw createRequestError(
         response.status,
         payload?.message || 'GitHub API request failed.',
-        'HOSTED_GITHUB_API_FAILED',
+        { code: 'HOSTED_GITHUB_API_FAILED' },
       );
     }
 
@@ -141,7 +140,9 @@ export class GitHubAppClient {
   async createInstallationAccessToken(installationId, { appJwt = null } = {}) {
     const normalizedInstallationId = String(installationId ?? '').trim();
     if (!normalizedInstallationId) {
-      throw createRequestError(400, 'GitHub installation id is required.', 'HOSTED_GITHUB_INSTALLATION_REQUIRED');
+      throw createRequestError(400, 'GitHub installation id is required.', {
+        code: 'HOSTED_GITHUB_INSTALLATION_REQUIRED',
+      });
     }
 
     const payload = await this.request(`/app/installations/${encodeURIComponent(normalizedInstallationId)}/access_tokens`, {
@@ -150,7 +151,9 @@ export class GitHubAppClient {
     });
     const token = String(payload?.token ?? '').trim();
     if (!token) {
-      throw createRequestError(502, 'GitHub did not return an installation access token.', 'HOSTED_GITHUB_TOKEN_MISSING');
+      throw createRequestError(502, 'GitHub did not return an installation access token.', {
+        code: 'HOSTED_GITHUB_TOKEN_MISSING',
+      });
     }
     return token;
   }
@@ -158,7 +161,9 @@ export class GitHubAppClient {
   async getInstallation(installationId, { appJwt = null } = {}) {
     const normalizedInstallationId = String(installationId ?? '').trim();
     if (!normalizedInstallationId) {
-      throw createRequestError(400, 'GitHub installation id is required.', 'HOSTED_GITHUB_INSTALLATION_REQUIRED');
+      throw createRequestError(400, 'GitHub installation id is required.', {
+        code: 'HOSTED_GITHUB_INSTALLATION_REQUIRED',
+      });
     }
 
     return this.request(`/app/installations/${encodeURIComponent(normalizedInstallationId)}`, {
@@ -176,7 +181,9 @@ export class GitHubAppClient {
   async resolveVaultSourceFromInstallation(installationId) {
     const normalizedInstallationId = String(installationId ?? '').trim();
     if (!normalizedInstallationId) {
-      throw createRequestError(400, 'GitHub installation id is required.', 'HOSTED_GITHUB_INSTALLATION_REQUIRED');
+      throw createRequestError(400, 'GitHub installation id is required.', {
+        code: 'HOSTED_GITHUB_INSTALLATION_REQUIRED',
+      });
     }
 
     const appJwt = this.createAppJwt();
@@ -189,7 +196,7 @@ export class GitHubAppClient {
       throw createRequestError(
         409,
         'GitHub App installation must grant access to exactly one selected repository.',
-        'HOSTED_GITHUB_REPOSITORY_SELECTION_REQUIRED',
+        { code: 'HOSTED_GITHUB_REPOSITORY_SELECTION_REQUIRED' },
       );
     }
 

package/src/server/infrastructure/http/create-git-api-command-handler.js

@@ -1,4 +1,4 @@
-import { getRequestErrorStatusCode } from './http-errors.js';
+import { handleApiError, readRequestId } from './http-request-helpers.js';
 import { jsonResponse } from './http-response.js';
 import { parseJsonBody } from './request-body.js';
 import { createEmptyWorkspaceChange, hasWorkspaceMutation } from '../../../domain/workspace-change.js';
@@ -13,27 +13,6 @@ async function parseRequiredBody(req, res, fieldName) {
   return body;
 }
 
-function handleGitError(req, res, error, logMessage, fallbackMessage) {
-  const statusCode = getRequestErrorStatusCode(error);
-  if (statusCode) {
-    const payload = { error: error.message };
-    if (typeof error?.requestCode === 'string') {
-      payload.code = error.requestCode;
-    }
-    jsonResponse(req, res, statusCode, payload);
-    return true;
-  }
-
-  console.error(logMessage, error.message);
-  jsonResponse(req, res, 500, { error: fallbackMessage });
-  return true;
-}
-
-function readRequestId(req) {
-  const value = String(req.headers['x-collabmd-request-id'] || '').trim();
-  return value ? value.slice(0, 120) : null;
-}
-
 async function applyWorkspaceMutationEffects({
   action,
   req,
@@ -79,7 +58,7 @@ export function createGitApiCommandHandler({
           workspaceMutationCoordinator,
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to stage git file:', 'Failed to stage git file');
+        handleApiError(req, res, error, '[api] Failed to stage git file:', 'Failed to stage git file');
       }
       return true;
     }
@@ -100,7 +79,7 @@ export function createGitApiCommandHandler({
           workspaceMutationCoordinator,
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to unstage git file:', 'Failed to unstage git file');
+        handleApiError(req, res, error, '[api] Failed to unstage git file:', 'Failed to unstage git file');
       }
       return true;
     }
@@ -124,7 +103,7 @@ export function createGitApiCommandHandler({
           workspaceMutationCoordinator,
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to commit staged changes:', 'Failed to commit staged changes');
+        handleApiError(req, res, error, '[api] Failed to commit staged changes:', 'Failed to commit staged changes');
       }
       return true;
     }
@@ -140,7 +119,7 @@ export function createGitApiCommandHandler({
           workspaceMutationCoordinator,
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to push git branch:', 'Failed to push git branch');
+        handleApiError(req, res, error, '[api] Failed to push git branch:', 'Failed to push git branch');
       }
       return true;
     }
@@ -156,7 +135,7 @@ export function createGitApiCommandHandler({
           workspaceMutationCoordinator,
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to pull git branch:', 'Failed to pull git branch');
+        handleApiError(req, res, error, '[api] Failed to pull git branch:', 'Failed to pull git branch');
       }
       return true;
     }
@@ -177,7 +156,7 @@ export function createGitApiCommandHandler({
           workspaceMutationCoordinator,
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to reset git file:', 'Failed to reset git file');
+        handleApiError(req, res, error, '[api] Failed to reset git file:', 'Failed to reset git file');
       }
       return true;
     }

package/src/server/infrastructure/http/create-git-api-query-handler.js

@@ -1,4 +1,4 @@
-import { getRequestErrorStatusCode } from './http-errors.js';
+import { handleApiError } from './http-request-helpers.js';
 import { jsonResponse } from './http-response.js';
 
 function resolveDiffScope(requestUrl) {
@@ -28,22 +28,6 @@ function readHistoryOffset(value) {
   return Number.isFinite(parsed) ? parsed : 0;
 }
 
-function handleGitError(req, res, error, message, fallback) {
-  const statusCode = getRequestErrorStatusCode(error);
-  if (statusCode) {
-    const payload = { error: error.message };
-    if (typeof error?.requestCode === 'string') {
-      payload.code = error.requestCode;
-    }
-    jsonResponse(req, res, statusCode, payload);
-    return true;
-  }
-
-  console.error(message, error.message);
-  jsonResponse(req, res, 500, { error: fallback });
-  return true;
-}
-
 export function createGitApiQueryHandler({ gitService }) {
   return async function handleGitApiQuery(req, res, requestUrl) {
     if (requestUrl.pathname === '/api/git/status' && req.method === 'GET') {
@@ -52,7 +36,7 @@ export function createGitApiQueryHandler({ gitService }) {
           force: isTruthyParam(requestUrl.searchParams.get('force')),
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to read git status:', 'Failed to read git status');
+        handleApiError(req, res, error, '[api] Failed to read git status:', 'Failed to read git status');
       }
       return true;
     }
@@ -66,7 +50,7 @@ export function createGitApiQueryHandler({ gitService }) {
           scope: resolveDiffScope(requestUrl),
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to read git diff:', 'Failed to read git diff');
+        handleApiError(req, res, error, '[api] Failed to read git diff:', 'Failed to read git diff');
       }
       return true;
     }
@@ -78,7 +62,7 @@ export function createGitApiQueryHandler({ gitService }) {
           offset: readHistoryOffset(requestUrl.searchParams.get('offset')),
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to read git history:', 'Failed to read git history');
+        handleApiError(req, res, error, '[api] Failed to read git history:', 'Failed to read git history');
       }
       return true;
     }
@@ -91,7 +75,7 @@ export function createGitApiQueryHandler({ gitService }) {
           path: requestUrl.searchParams.get('path'),
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to read git file history:', 'Failed to read git file history');
+        handleApiError(req, res, error, '[api] Failed to read git file history:', 'Failed to read git file history');
       }
       return true;
     }
@@ -105,7 +89,7 @@ export function createGitApiQueryHandler({ gitService }) {
           path: requestUrl.searchParams.get('path'),
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to read git commit:', 'Failed to read git commit');
+        handleApiError(req, res, error, '[api] Failed to read git commit:', 'Failed to read git commit');
       }
       return true;
     }
@@ -117,7 +101,7 @@ export function createGitApiQueryHandler({ gitService }) {
           path: requestUrl.searchParams.get('path'),
         }));
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to read git file snapshot:', 'Failed to read git file snapshot');
+        handleApiError(req, res, error, '[api] Failed to read git file snapshot:', 'Failed to read git file snapshot');
       }
       return true;
     }
@@ -128,7 +112,7 @@ export function createGitApiQueryHandler({ gitService }) {
           backups: await gitService.listPullBackups(),
         });
       } catch (error) {
-        handleGitError(req, res, error, '[api] Failed to read pull backups:', 'Failed to read pull backups');
+        handleApiError(req, res, error, '[api] Failed to read pull backups:', 'Failed to read pull backups');
       }
       return true;
     }

package/src/server/infrastructure/http/create-request-handler.js

@@ -1,9 +1,11 @@
 import { createAuthApiHandler } from './create-auth-api-handler.js';
-import { createGitApiHandler } from './create-git-api-handler.js';
+import { createGitApiCommandHandler } from './create-git-api-command-handler.js';
+import { createGitApiQueryHandler } from './create-git-api-query-handler.js';
 import { createHostedApiHandler } from './create-hosted-api-handler.js';
-import { createEsmProxyHandler } from './create-esm-proxy-handler.js';
+import { createPlantUmlApiHandler } from './create-plantuml-api-handler.js';
 import { createStaticHandler } from './create-static-handler.js';
-import { createVaultApiHandler } from './create-vault-api-handler.js';
+import { createVaultApiCommandHandler } from './create-vault-api-command-handler.js';
+import { createVaultApiQueryHandler } from './create-vault-api-query-handler.js';
 import { parseJsonBody } from './request-body.js';
 import {
   applyCorsHeaders,
@@ -42,7 +44,7 @@ export function createRequestHandler(
   vaultFileStore,
   backlinkIndex,
   baseQueryService = null,
-  docxExporter = null,
+  renderDocx = null,
   roomRegistry = null,
   plantUmlRenderer = null,
   gitService = null,
@@ -53,7 +55,6 @@ export function createRequestHandler(
   hostedWorkspaceService = null,
   githubSetupFlow = null,
 ) {
-  const handleEsmProxy = createEsmProxyHandler();
   const handleStaticRequest = createStaticHandler(config, authService, searchService);
   const handleAuthApi = createAuthApiHandler({ authService });
   const handleHostedApi = createHostedApiHandler({
@@ -61,25 +62,28 @@ export function createRequestHandler(
     githubSetupFlow,
     hostedWorkspaceService,
   });
-  const handleGitApi = createGitApiHandler({
+  const handleGitApiQuery = createGitApiQueryHandler({ gitService });
+  const handleGitApiCommand = createGitApiCommandHandler({
     authService,
-    backlinkIndex,
     gitService,
-    roomRegistry,
-    vaultFileStore,
     workspaceMutationCoordinator,
   });
-  const handleVaultApi = createVaultApiHandler({
+  const handleVaultApiQuery = createVaultApiQueryHandler({
     baseQueryService,
     backlinkIndex,
     config,
-    docxExporter,
-    plantUmlRenderer,
-    roomRegistry,
     searchService,
     vaultFileStore,
     workspaceMutationCoordinator,
   });
+  const handleVaultApiCommand = createVaultApiCommandHandler({
+    backlinkIndex,
+    renderDocx,
+    roomRegistry,
+    vaultFileStore,
+    workspaceMutationCoordinator,
+  });
+  const handlePlantUmlApi = createPlantUmlApiHandler({ plantUmlRenderer });
 
   function handleBasePathRedirect(req, res, originalRequestUrl) {
     if (
@@ -189,10 +193,6 @@ export function createRequestHandler(
       return;
     }
 
-    if (await handleEsmProxy(req, res, requestUrl)) {
-      return;
-    }
-
     if (requestUrl.pathname.startsWith('/api/')) {
       const authorization = authService.authorizeApiRequest(req);
       if (!authorization.ok) {
@@ -209,11 +209,30 @@ export function createRequestHandler(
       }
     }
 
-    if (await handleVaultApi(req, res, requestUrl)) {
-      return;
+    if (requestUrl.pathname.startsWith('/api/')) {
+      if (await handleVaultApiQuery(req, res, requestUrl)) {
+        return;
+      }
+      if (await handleVaultApiCommand(req, res, requestUrl)) {
+        return;
+      }
+      if (await handlePlantUmlApi(req, res, requestUrl)) {
+        return;
+      }
     }
 
-    if (await handleGitApi(req, res, requestUrl)) {
+    if (requestUrl.pathname.startsWith('/api/git')) {
+      if (!gitService) {
+        jsonResponse(req, res, 503, { error: 'Git integration is not configured' });
+        return;
+      }
+      if (await handleGitApiQuery(req, res, requestUrl)) {
+        return;
+      }
+      if (await handleGitApiCommand(req, res, requestUrl)) {
+        return;
+      }
+      jsonResponse(req, res, 404, { error: 'Git API endpoint not found' });
       return;
     }
 

package/src/server/infrastructure/http/create-vault-api-command-handler.js

@@ -1,30 +1,23 @@
 import { basename } from 'node:path';
-import { createRequestError, getRequestErrorStatusCode } from './http-errors.js';
-import { jsonResponse, sendResponse } from './http-response.js';
+import { createRequestError } from './http-errors.js';
+import { handleApiError, readRequestId } from './http-request-helpers.js';
+import {
+  createSafeAsciiFilename,
+  encodeContentDispositionFilename,
+  jsonResponse,
+  sendResponse,
+} from './http-response.js';
 import { parseJsonBody, readBinaryRequestBody } from './request-body.js';
 
 const DOCX_EXPORT_REQUEST_LIMIT_BYTES = 33_554_432;
 const DOCX_MIME_TYPE = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
 
-function encodeContentDispositionFilename(fileName) {
-  return encodeURIComponent(String(fileName ?? ''))
-    .replace(/['()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
-}
-
-function createSafeAsciiFilename(fileName) {
-  const fallback = String(fileName ?? '')
-    .replace(/[^\x20-\x7E]+/g, '_')
-    .replace(/["\\]/g, '_')
-    .trim();
-  return fallback || 'document';
-}
-
 function createDocxDownloadHeaders(filePath) {
   const fileName = basename(String(filePath ?? 'document')).replace(/\.[^.]+$/u, '') || 'document';
   const exportFileName = `${fileName}.docx`;
   return {
     'Cache-Control': 'no-store',
-    'Content-Disposition': `attachment; filename="${createSafeAsciiFilename(exportFileName)}"; filename*=UTF-8''${encodeContentDispositionFilename(exportFileName)}`,
+    'Content-Disposition': `attachment; filename="${createSafeAsciiFilename(exportFileName, 'document')}"; filename*=UTF-8''${encodeContentDispositionFilename(exportFileName)}`,
     'Content-Type': DOCX_MIME_TYPE,
     'X-Content-Type-Options': 'nosniff',
   };
@@ -43,28 +36,11 @@ function decodeHeaderMetadata(value) {
   }
 }
 
-function readRequestId(req) {
-  const value = String(req.headers['x-collabmd-request-id'] || '').trim();
-  return value ? value.slice(0, 120) : null;
-}
-
-function handleVaultError(req, res, error, logMessage, fallbackMessage) {
-  const statusCode = getRequestErrorStatusCode(error);
-  if (statusCode) {
-    jsonResponse(req, res, statusCode, { error: error.message });
-    return true;
-  }
-
-  console.error(logMessage, error.message);
-  jsonResponse(req, res, 500, { error: fallbackMessage });
-  return true;
-}
-
 function getDirectoryDeleteStatusCode(message = '') {
   return String(message).includes('Directory is not empty') ? 409 : 400;
 }
 
-async function handleExportDocx({ docxExporter }, req, res) {
+async function handleExportDocx({ renderDocx }, req, res) {
   try {
     const body = await parseJsonBody(req, DOCX_EXPORT_REQUEST_LIMIT_BYTES);
     if (!body?.filePath || typeof body?.html !== 'string') {
@@ -72,12 +48,12 @@ async function handleExportDocx({ docxExporter }, req, res) {
       return true;
     }
 
-    if (!docxExporter?.render) {
+    if (typeof renderDocx !== 'function') {
       jsonResponse(req, res, 503, { error: 'DOCX export is unavailable' });
       return true;
     }
 
-    const docxBuffer = await docxExporter.render({
+    const docxBuffer = await renderDocx({
       html: body.html,
       title: body.title || '',
     });
@@ -88,7 +64,7 @@ async function handleExportDocx({ docxExporter }, req, res) {
       statusCode: 200,
     });
   } catch (error) {
-    handleVaultError(req, res, error, '[api] Failed to export DOCX:', 'Failed to export DOCX');
+    handleApiError(req, res, error, '[api] Failed to export DOCX:', 'Failed to export DOCX');
   }
   return true;
 }
@@ -113,7 +89,7 @@ async function handleWriteFile({ workspaceMutationCoordinator }, req, res) {
 
     jsonResponse(req, res, 200, { ok: true });
   } catch (error) {
-    handleVaultError(req, res, error, '[api] Failed to write file:', 'Failed to write file');
+    handleApiError(req, res, error, '[api] Failed to write file:', 'Failed to write file');
   }
   return true;
 }
@@ -148,7 +124,7 @@ async function handleUploadAttachment({ workspaceMutationCoordinator }, req, res
       path: result.path,
     });
   } catch (error) {
-    handleVaultError(req, res, error, '[api] Failed to upload attachment:', 'Failed to upload attachment');
+    handleApiError(req, res, error, '[api] Failed to upload attachment:', 'Failed to upload attachment');
   }
   return true;
 }
@@ -172,7 +148,7 @@ async function handleCreateFile({ workspaceMutationCoordinator }, req, res) {
     }
     jsonResponse(req, res, 201, { ok: true, path: body.path });
   } catch (error) {
-    handleVaultError(req, res, error, '[api] Failed to create file:', 'Failed to create file');
+    handleApiError(req, res, error, '[api] Failed to create file:', 'Failed to create file');
   }
   return true;
 }
@@ -220,7 +196,7 @@ async function handleRenameFile({ workspaceMutationCoordinator }, req, res) {
     }
     jsonResponse(req, res, 200, { ok: true, path: body.newPath });
   } catch (error) {
-    handleVaultError(req, res, error, '[api] Failed to rename file:', 'Failed to rename file');
+    handleApiError(req, res, error, '[api] Failed to rename file:', 'Failed to rename file');
   }
   return true;
 }
@@ -244,7 +220,7 @@ async function handleCreateDirectory({ workspaceMutationCoordinator }, req, res)
 
     jsonResponse(req, res, 201, { ok: true });
   } catch (error) {
-    handleVaultError(req, res, error, '[api] Failed to create directory:', 'Failed to create directory');
+    handleApiError(req, res, error, '[api] Failed to create directory:', 'Failed to create directory');
   }
   return true;
 }
@@ -269,7 +245,7 @@ async function handleRenameDirectory({ workspaceMutationCoordinator }, req, res)
 
     jsonResponse(req, res, 200, { ok: true, path: body.newPath });
   } catch (error) {
-    handleVaultError(req, res, error, '[api] Failed to rename directory:', 'Failed to rename directory');
+    handleApiError(req, res, error, '[api] Failed to rename directory:', 'Failed to rename directory');
   }
   return true;
 }
@@ -295,7 +271,7 @@ async function handleDeleteDirectory({ workspaceMutationCoordinator }, req, res,
 
     jsonResponse(req, res, 200, { ok: true });
   } catch (error) {
-    handleVaultError(req, res, error, '[api] Failed to delete directory:', 'Failed to delete directory');
+    handleApiError(req, res, error, '[api] Failed to delete directory:', 'Failed to delete directory');
   }
   return true;
 }
@@ -313,11 +289,11 @@ const ROUTE_TABLE = [
 ];
 
 export function createVaultApiCommandHandler({
-  docxExporter = null,
+  renderDocx = null,
   vaultFileStore,
   workspaceMutationCoordinator = null,
 }) {
-  const context = { docxExporter, vaultFileStore, workspaceMutationCoordinator };
+  const context = { renderDocx, vaultFileStore, workspaceMutationCoordinator };
 
   return async function handleVaultApiCommand(req, res, requestUrl) {
     for (const route of ROUTE_TABLE) {

package/src/server/infrastructure/http/create-vault-api-query-handler.js

@@ -6,26 +6,19 @@ import { join } from 'node:path';
 import { isImageAttachmentFilePath } from '../../../domain/file-kind.js';
 import { isIgnoredVaultEntry } from '../persistence/path-utils.js';
 import { parseJsonBody } from './request-body.js';
-import { jsonResponse, sendResponse, sendStreamResponse } from './http-response.js';
+import {
+  createSafeAsciiFilename,
+  encodeContentDispositionFilename,
+  jsonResponse,
+  sendResponse,
+  sendStreamResponse,
+} from './http-response.js';
 
 const SVG_MIME_TYPE = 'image/svg+xml';
 const SVG_ATTACHMENT_CSP = "default-src 'none'; img-src 'self' data: blob:; style-src 'unsafe-inline'; sandbox";
 const DEFAULT_MAX_ARCHIVE_ENTRIES = 10_000;
 const DEFAULT_MAX_DOWNLOAD_FILE_BYTES = 268_435_456;
 
-function encodeContentDispositionFilename(fileName) {
-  return encodeURIComponent(String(fileName ?? ''))
-    .replace(/['()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
-}
-
-function createSafeAsciiFilename(fileName) {
-  const fallback = String(fileName ?? '')
-    .replace(/[^\x20-\x7E]+/g, '_')
-    .replace(/["\\]/g, '_')
-    .trim();
-  return fallback || 'attachment';
-}
-
 function createAttachmentHeaders(attachment) {
   const fileName = basename(String(attachment?.path ?? 'attachment'));
   const headers = {

package/src/server/infrastructure/http/http-errors.js

@@ -1,6 +1,12 @@
-export function createRequestError(statusCode, message) {
+export function createRequestError(statusCode, message, { code = null, requestCode = null } = {}) {
   const error = new Error(message);
   error.statusCode = statusCode;
+  if (code) {
+    error.code = code;
+  }
+  if (requestCode) {
+    error.requestCode = requestCode;
+  }
   return error;
 }
 

package/src/server/infrastructure/http/http-request-helpers.js

@@ -0,0 +1,23 @@
+import { getRequestErrorStatusCode } from './http-errors.js';
+import { jsonResponse } from './http-response.js';
+
+export function readRequestId(req) {
+  const value = String(req.headers['x-collabmd-request-id'] || '').trim();
+  return value ? value.slice(0, 120) : null;
+}
+
+export function handleApiError(req, res, error, logMessage, fallbackMessage) {
+  const statusCode = getRequestErrorStatusCode(error);
+  if (statusCode) {
+    const payload = { error: error.message };
+    if (typeof error?.requestCode === 'string') {
+      payload.code = error.requestCode;
+    }
+    jsonResponse(req, res, statusCode, payload);
+    return true;
+  }
+
+  console.error(logMessage, error.message);
+  jsonResponse(req, res, 500, { error: fallbackMessage });
+  return true;
+}

package/src/server/infrastructure/http/http-response.js

@@ -7,6 +7,19 @@ import {
 const COMPRESSIBLE_CONTENT_TYPE_PATTERN = /^(?:text\/|application\/(?:javascript|json|xml)|image\/svg\+xml)/i;
 const MIN_COMPRESSIBLE_BYTES = 1024;
 
+export function encodeContentDispositionFilename(fileName) {
+  return encodeURIComponent(String(fileName ?? ''))
+    .replace(/['()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+export function createSafeAsciiFilename(fileName, fallback = 'attachment') {
+  const normalized = String(fileName ?? '')
+    .replace(/[^\x20-\x7E]+/g, '_')
+    .replace(/["\\]/g, '_')
+    .trim();
+  return normalized || fallback;
+}
+
 export const SECURITY_HEADERS = {
   'Referrer-Policy': 'strict-origin-when-cross-origin',
   'X-Content-Type-Options': 'nosniff',