@jgardner04/ghost-mcp-server 1.13.5 → 1.14.1

package/src/services/imageProcessingService.js

@@ -1,96 +1,140 @@
 import sharp from 'sharp';
 import path from 'path';
-import fs from 'fs';
-import Joi from 'joi';
+import fsp from 'fs/promises';
+import { z } from 'zod';
 import { createContextLogger } from '../utils/logger.js';
 
-// Define processing parameters (e.g., max width)
 const MAX_WIDTH = 1200;
-const OUTPUT_QUALITY = 80; // JPEG quality
+const JPEG_QUALITY = 80;
 
-/**
- * Processes an image: resizes if too large, ensures JPEG format (configurable).
- * @param {string} inputPath - Path to the original uploaded image.
- * @param {string} outputDir - Directory to save the processed image.
- * @returns {Promise<string>} Path to the processed image.
- */
-// Validation schema for processing parameters
-const processImageSchema = Joi.object({
-  inputPath: Joi.string().required(),
-  outputDir: Joi.string().required(),
+// Formats we re-encode via sharp when the image is oversized.
+// Everything else is passed through untouched to preserve fidelity
+// (SVG vectors, GIF animation, ICO, exotic formats).
+const RESIZABLE_FORMATS = new Set(['jpeg', 'png', 'webp']);
+
+const EXT_BY_FORMAT = {
+  jpeg: '.jpg',
+  png: '.png',
+  webp: '.webp',
+  gif: '.gif',
+  svg: '.svg',
+  // ICO has no sharp `format` name; detected by extension.
+};
+
+const processImageParamsSchema = z.object({
+  inputPath: z.string().min(1),
+  outputDir: z.string().min(1),
 });
 
-const processImage = async (inputPath, outputDir) => {
+const processImageOptsSchema = z
+  .object({
+    purpose: z.enum(['image', 'profile_image', 'icon']).optional(),
+  })
+  .optional();
+
+/**
+ * Process an image for upload to Ghost.
+ *
+ * Preserves the original format. Resizes (preserving format) only for
+ * raster formats sharp can safely re-encode — JPEG, PNG, WEBP — when
+ * wider than MAX_WIDTH. SVG, GIF, ICO, and unrecognized formats are
+ * copied byte-for-byte so vectors, animation frames, and icon metadata
+ * survive the round trip.
+ *
+ * @param {string} inputPath - Absolute path to the source image.
+ * @param {string} outputDir - Directory to write the processed file into.
+ * @param {{ purpose?: 'image'|'profile_image'|'icon' }} [opts]
+ * @returns {Promise<string>} Absolute path to the processed (or copied) file.
+ */
+export async function processImage(inputPath, outputDir, opts = {}) {
   const logger = createContextLogger('image-processing');
 
-  // Validate inputs to prevent path injection
-  const { error } = processImageSchema.validate({ inputPath, outputDir });
-  if (error) {
-    logger.error('Invalid processing parameters', {
-      error: error.details[0].message,
-      inputPath: inputPath ? path.basename(inputPath) : 'undefined',
-      outputDir: outputDir ? path.basename(outputDir) : 'undefined',
-    });
+  const params = processImageParamsSchema.safeParse({ inputPath, outputDir });
+  if (!params.success) {
     throw new Error('Invalid processing parameters');
   }
+  processImageOptsSchema.parse(opts);
 
-  // Ensure paths are safe
-  const resolvedInputPath = path.resolve(inputPath);
+  const resolvedInput = path.resolve(inputPath);
   const resolvedOutputDir = path.resolve(outputDir);
 
-  // Verify input file exists
-  if (!fs.existsSync(resolvedInputPath)) {
+  try {
+    await fsp.access(resolvedInput);
+  } catch {
     throw new Error('Input file does not exist');
   }
 
-  const filename = path.basename(resolvedInputPath);
-  const nameWithoutExt = filename.split('.').slice(0, -1).join('.');
-  // Use timestamp for unique output filename
+  const inputExt = path.extname(resolvedInput).toLowerCase();
+  const baseName = path.basename(resolvedInput, path.extname(resolvedInput));
   const timestamp = Date.now();
-  const outputFilename = `processed-${timestamp}-${nameWithoutExt}.jpg`;
-  const outputPath = path.join(resolvedOutputDir, outputFilename);
 
   try {
-    logger.info('Processing image', {
-      inputFile: path.basename(inputPath),
-      outputDir: path.basename(outputDir),
-    });
-    const image = sharp(inputPath);
+    // Non-raster passthrough: SVG and ICO are never handed to sharp.
+    // (sharp can read SVG but would rasterize it, destroying the vector.)
+    if (inputExt === '.svg' || inputExt === '.ico') {
+      return await passthrough(resolvedInput, resolvedOutputDir, baseName, timestamp, inputExt);
+    }
+
+    const image = sharp(resolvedInput);
     const metadata = await image.metadata();
+    const format = metadata.format; // 'jpeg' | 'png' | 'webp' | 'gif' | 'svg' | ...
 
-    let processedImage = image;
+    // GIF: never re-encode — sharp would drop animation frames.
+    // SVG (if it slipped through by extension mismatch): also passthrough.
+    if (format === 'gif' || format === 'svg') {
+      const ext = EXT_BY_FORMAT[format] || inputExt || '';
+      return await passthrough(resolvedInput, resolvedOutputDir, baseName, timestamp, ext);
+    }
 
-    // Resize if wider than MAX_WIDTH
-    if (metadata.width && metadata.width > MAX_WIDTH) {
-      logger.info('Resizing image', {
-        originalWidth: metadata.width,
-        targetWidth: MAX_WIDTH,
+    // Unknown / unsupported format: safest is passthrough.
+    if (!RESIZABLE_FORMATS.has(format)) {
+      logger.info('Unknown format, passing through', {
+        format,
         inputFile: path.basename(inputPath),
       });
-      processedImage = processedImage.resize({ width: MAX_WIDTH });
+      return await passthrough(resolvedInput, resolvedOutputDir, baseName, timestamp, inputExt);
     }
 
-    // Convert to JPEG with specified quality
-    // You could add options for PNG/WebP etc. if needed
-    await processedImage.jpeg({ quality: OUTPUT_QUALITY }).toFile(outputPath);
+    const ext = EXT_BY_FORMAT[format];
+    const outputPath = path.join(resolvedOutputDir, `processed-${timestamp}-${baseName}${ext}`);
 
-    logger.info('Image processing completed', {
+    // Passthrough when no resize is needed — avoids generation loss.
+    if (!metadata.width || metadata.width <= MAX_WIDTH) {
+      await fsp.copyFile(resolvedInput, outputPath);
+      logger.info('Image within size limits, passthrough copy', {
+        format,
+        width: metadata.width,
+        inputFile: path.basename(inputPath),
+      });
+      return outputPath;
+    }
+
+    logger.info('Resizing image', {
+      format,
+      originalWidth: metadata.width,
+      targetWidth: MAX_WIDTH,
       inputFile: path.basename(inputPath),
-      outputFile: path.basename(outputPath),
-      originalSize: metadata.size,
-      quality: OUTPUT_QUALITY,
     });
+
+    // sharp picks the encoder from outputPath extension (EXT_BY_FORMAT),
+    // so only JPEG needs the explicit call here to set quality. PNG/WEBP
+    // would be redundant.
+    let pipeline = image.resize({ width: MAX_WIDTH });
+    if (format === 'jpeg') pipeline = pipeline.jpeg({ quality: JPEG_QUALITY });
+
+    await pipeline.toFile(outputPath);
     return outputPath;
   } catch (error) {
     logger.error('Image processing failed', {
       inputFile: path.basename(inputPath),
       error: error.message,
-      stack: error.stack,
     });
-    // If processing fails, maybe fall back to using the original?
-    // Or throw the error to fail the upload.
     throw new Error('Image processing failed: ' + error.message, { cause: error });
   }
-};
+}
 
-export { processImage };
+async function passthrough(inputPath, outputDir, baseName, timestamp, ext) {
+  const outputPath = path.join(outputDir, `processed-${timestamp}-${baseName}${ext}`);
+  await fsp.copyFile(inputPath, outputPath);
+  return outputPath;
+}

package/src/services/images.js

@@ -2,19 +2,46 @@ import { GhostAPIError, ValidationError } from '../errors/index.js';
 import { handleApiRequest } from './ghostApiClient.js';
 import { validators } from './validators.js';
 
+const ALLOWED_PURPOSES = new Set(['image', 'profile_image', 'icon']);
+const REF_MAX_LENGTH = 200;
+
 /**
  * Uploads an image to Ghost CMS from a local file path.
- * @param {string} imagePath - Absolute path to the image file
- * @returns {Promise<Object>} The uploaded image object with URL
- * @throws {ValidationError} If the path is invalid or upload fails
- * @throws {NotFoundError} If the file does not exist
- * @throws {GhostAPIError} If the API request fails
+ *
+ * @param {string} imagePath - Absolute path to the image file.
+ * @param {object} [opts]
+ * @param {'image'|'profile_image'|'icon'} [opts.purpose] - Intended use.
+ *   Ghost applies format/size validation per purpose (icon/profile_image
+ *   must be square; icon also accepts ICO).
+ * @param {string} [opts.ref] - Caller-supplied identifier (e.g. original
+ *   filename). Ghost echoes it back in the response. Max 200 chars.
+ * @returns {Promise<Object>} The uploaded image object with URL (and ref,
+ *   if provided and the SDK forwards it).
+ * @throws {ValidationError} If inputs are invalid or upload fails.
+ * @throws {NotFoundError} If the file does not exist.
+ * @throws {GhostAPIError} If the API request fails.
  */
-export async function uploadImage(imagePath) {
-  // Validate input
+export async function uploadImage(imagePath, opts = {}) {
   await validators.validateImagePath(imagePath);
 
+  const { purpose, ref } = opts;
+  if (purpose !== undefined && !ALLOWED_PURPOSES.has(purpose)) {
+    throw new ValidationError(
+      `Invalid purpose "${purpose}". Must be one of: ${[...ALLOWED_PURPOSES].join(', ')}`
+    );
+  }
+  if (ref !== undefined) {
+    if (typeof ref !== 'string') {
+      throw new ValidationError('ref must be a string');
+    }
+    if (ref.length > REF_MAX_LENGTH) {
+      throw new ValidationError(`ref cannot exceed ${REF_MAX_LENGTH} characters`);
+    }
+  }
+
   const imageData = { file: imagePath };
+  if (purpose !== undefined) imageData.purpose = purpose;
+  if (ref !== undefined) imageData.ref = ref;
 
   try {
     return await handleApiRequest('images', 'upload', imageData);

package/src/services/pageService.js

@@ -41,8 +41,8 @@ const pageInputSchema = Joi.object({
   published_at: Joi.string().isoDate().optional(),
   // NO tags field - pages don't support tags
   feature_image: Joi.string().uri().optional(),
-  feature_image_alt: Joi.string().max(255).optional(),
-  feature_image_caption: Joi.string().max(500).optional(),
+  feature_image_alt: Joi.string().max(191).optional(),
+  feature_image_caption: Joi.string().max(5000).optional(),
   meta_title: Joi.string().max(70).optional(),
   meta_description: Joi.string().max(160).optional(),
 });

package/src/utils/__tests__/formatErrorResponse.test.js

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { formatErrorResponse } from '../formatErrorResponse.js';
+import { GhostAPIError, ValidationError, NotFoundError } from '../../errors/index.js';
+
+function parseJsonBlock(text) {
+  const match = text.match(/```json\n([\s\S]+?)\n```/);
+  expect(match, `no JSON block in: ${text}`).toBeTruthy();
+  return JSON.parse(match[1]);
+}
+
+describe('formatErrorResponse', () => {
+  const originalEnv = process.env.GHOST_ADMIN_API_KEY;
+
+  beforeEach(() => {
+    process.env.GHOST_ADMIN_API_KEY = '';
+  });
+
+  afterEach(() => {
+    if (originalEnv === undefined) delete process.env.GHOST_ADMIN_API_KEY;
+    else process.env.GHOST_ADMIN_API_KEY = originalEnv;
+  });
+
+  it('returns consistent envelope with error key for generic Error (no ghost key)', () => {
+    const response = formatErrorResponse(new Error('boom'), 'ghost_get_posts');
+    expect(response.isError).toBe(true);
+    expect(response.content[0].type).toBe('text');
+    const envelope = parseJsonBlock(response.content[0].text);
+    expect(envelope.error).toBeDefined();
+    expect(envelope.error.message).toBe('boom');
+    expect(envelope).not.toHaveProperty('ghost');
+    expect(response.content[0].text).toContain('Error in ghost_get_posts: boom');
+  });
+
+  it('includes gated ghost sub-object for GhostAPIError', () => {
+    const err = new GhostAPIError('posts.edit', 'Title is required', 422);
+    const response = formatErrorResponse(err, 'ghost_update_post');
+    const envelope = parseJsonBlock(response.content[0].text);
+    expect(envelope.error.name).toBe('GhostAPIError');
+    expect(envelope.error.code).toBe('GHOST_VALIDATION_ERROR');
+    expect(envelope.ghost).toBeDefined();
+    expect(envelope.ghost.operation).toBe('posts.edit');
+    expect(envelope.ghost.statusCode).toBe(422);
+    expect(envelope.ghost.originalMessage).toBe('Title is required');
+    expect(response.content[0].text).toContain('422');
+    expect(response.content[0].text).toContain('posts.edit');
+    expect(response.content[0].text).toContain('Title is required');
+  });
+
+  it('uses raw ghostStatusCode (not remapped statusCode) in ghost envelope', () => {
+    const err = new GhostAPIError('posts.edit', 'bad', 422);
+    // GhostAPIError remaps 422 -> 400 for .statusCode; ghost.statusCode must be 422
+    expect(err.statusCode).toBe(400);
+    expect(err.ghostStatusCode).toBe(422);
+    const envelope = parseJsonBlock(formatErrorResponse(err, 'ghost_update_post').content[0].text);
+    expect(envelope.ghost.statusCode).toBe(422);
+    expect(envelope.error.statusCode).toBe(400);
+  });
+
+  it('does not leak GHOST_ADMIN_API_KEY in surfaced response', () => {
+    process.env.GHOST_ADMIN_API_KEY = 'plaintext-admin-key-xyz';
+    const err = new GhostAPIError(
+      'posts.edit',
+      'Ghost complained: token plaintext-admin-key-xyz invalid',
+      401
+    );
+    const response = formatErrorResponse(err, 'ghost_update_post');
+    expect(response.content[0].text).not.toContain('plaintext-admin-key-xyz');
+    expect(response.content[0].text).toContain('[REDACTED]');
+  });
+
+  it('does not leak Ghost-shaped admin key pattern in originalMessage', () => {
+    const fakeKey = `${'1'.repeat(24)}:${'2'.repeat(64)}`;
+    const err = new GhostAPIError('posts.edit', `failed with ${fakeKey}`, 401);
+    const response = formatErrorResponse(err, 'ghost_update_post');
+    expect(response.content[0].text).not.toContain(fakeKey);
+  });
+
+  it('produces envelope for ValidationError (no ghost key)', () => {
+    const err = new ValidationError('Validation failed', [
+      { field: 'title', message: 'required', type: 'invalid_type' },
+    ]);
+    const response = formatErrorResponse(err, 'ghost_update_post');
+    const envelope = parseJsonBlock(response.content[0].text);
+    expect(envelope.error.code).toBe('VALIDATION_ERROR');
+    expect(envelope).not.toHaveProperty('ghost');
+  });
+
+  it('produces envelope for NotFoundError (no ghost key)', () => {
+    const err = new NotFoundError('Post', 'abc');
+    const response = formatErrorResponse(err, 'ghost_get_post');
+    const envelope = parseJsonBlock(response.content[0].text);
+    expect(envelope.error.code).toBe('NOT_FOUND');
+    expect(envelope).not.toHaveProperty('ghost');
+  });
+
+  describe('extra context', () => {
+    it('includes and sanitizes extra context when provided', () => {
+      const extra = {
+        orphanedImage: { url: 'https://cdn.example/img.jpg?key=LEAK_ME_XYZ', ref: 'r1' },
+      };
+      const response = formatErrorResponse(new Error('boom'), 'ghost_set_feature_image', extra);
+      const envelope = parseJsonBlock(response.content[0].text);
+      expect(envelope.extra).toBeDefined();
+      expect(envelope.extra.orphanedImage.url).toContain('key=[REDACTED]');
+      expect(response.content[0].text).not.toContain('LEAK_ME_XYZ');
+    });
+
+    it('omits extra key entirely when arg is not provided', () => {
+      const envelope = parseJsonBlock(
+        formatErrorResponse(new Error('boom'), 'ghost_update_post').content[0].text
+      );
+      expect(envelope).not.toHaveProperty('extra');
+    });
+
+    it('omits extra key when arg is empty object (no empty-object leak)', () => {
+      const envelope = parseJsonBlock(
+        formatErrorResponse(new Error('boom'), 'ghost_update_post', {}).content[0].text
+      );
+      expect(envelope).not.toHaveProperty('extra');
+    });
+
+    it('combines error, ghost, and extra when all apply', () => {
+      const err = new GhostAPIError('posts.edit', 'bad', 422);
+      const envelope = parseJsonBlock(
+        formatErrorResponse(err, 'ghost_set_feature_image', { orphanedImage: { url: 'x' } })
+          .content[0].text
+      );
+      expect(envelope.error).toBeDefined();
+      expect(envelope.ghost).toBeDefined();
+      expect(envelope.extra).toBeDefined();
+    });
+  });
+
+  describe('ZodError coercion', () => {
+    it('coerces ZodError-shaped input to VALIDATION_ERROR / 400 envelope', () => {
+      const zodLike = Object.assign(new Error('zod'), {
+        name: 'ZodError',
+        issues: [{ path: ['purpose'], message: 'Invalid enum value', code: 'invalid_enum_value' }],
+      });
+      const envelope = parseJsonBlock(
+        formatErrorResponse(zodLike, 'ghost_upload_image').content[0].text
+      );
+      expect(envelope.error.code).toBe('VALIDATION_ERROR');
+      expect(envelope.error.statusCode).toBe(400);
+      expect(envelope.error.errors).toEqual([
+        { field: 'purpose', message: 'Invalid enum value', type: 'invalid_enum_value' },
+      ]);
+    });
+
+    it('does not coerce a non-ZodError error that happens to have an issues field', () => {
+      const notZod = Object.assign(new Error('unrelated'), { issues: [] });
+      const envelope = parseJsonBlock(
+        formatErrorResponse(notZod, 'ghost_update_post').content[0].text
+      );
+      expect(envelope.error.code).toBe('UNKNOWN');
+    });
+  });
+});

package/src/utils/__tests__/imageInputResolver.test.js

@@ -0,0 +1,134 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+
+import {
+  resolveLocalImagePath,
+  decodeBase64ToTempFile,
+  MAX_BASE64_BYTES,
+} from '../imageInputResolver.js';
+
+const tmpRoot = path.join(os.tmpdir(), `img-resolver-${Date.now()}`);
+const allowedRoot = path.join(tmpRoot, 'allowed');
+const outside = path.join(tmpRoot, 'outside');
+
+beforeAll(async () => {
+  await fs.mkdir(allowedRoot, { recursive: true });
+  await fs.mkdir(outside, { recursive: true });
+  await fs.writeFile(path.join(allowedRoot, 'ok.png'), 'fake-png');
+  await fs.writeFile(path.join(outside, 'secret.txt'), 'top secret');
+  await fs.symlink(path.join(outside, 'secret.txt'), path.join(allowedRoot, 'escape.txt'));
+});
+
+afterAll(async () => {
+  await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+describe('resolveLocalImagePath', () => {
+  const origRoot = process.env.GHOST_MCP_IMAGE_ROOT;
+
+  beforeEach(() => {
+    process.env.GHOST_MCP_IMAGE_ROOT = allowedRoot;
+  });
+
+  afterEach(() => {
+    if (origRoot === undefined) delete process.env.GHOST_MCP_IMAGE_ROOT;
+    else process.env.GHOST_MCP_IMAGE_ROOT = origRoot;
+  });
+
+  it('accepts a file inside the configured root', async () => {
+    const resolved = await resolveLocalImagePath(path.join(allowedRoot, 'ok.png'));
+    // Returns the realpath, which on macOS canonicalizes /var -> /private/var.
+    const canonical = await fs.realpath(path.join(allowedRoot, 'ok.png'));
+    expect(resolved).toBe(canonical);
+  });
+
+  it('rejects when GHOST_MCP_IMAGE_ROOT is unset (local-path mode disabled by default)', async () => {
+    delete process.env.GHOST_MCP_IMAGE_ROOT;
+    await expect(resolveLocalImagePath('/anywhere.png')).rejects.toThrow(
+      /GHOST_MCP_IMAGE_ROOT is not set/
+    );
+  });
+
+  it('rejects a path outside the configured root', async () => {
+    await expect(resolveLocalImagePath(path.join(outside, 'secret.txt'))).rejects.toThrow(
+      /outside the allowed root/
+    );
+  });
+
+  it('rejects a relative traversal attempt', async () => {
+    await expect(resolveLocalImagePath(`${allowedRoot}/../outside/secret.txt`)).rejects.toThrow(
+      /outside the allowed root/
+    );
+  });
+
+  it('rejects a symlink that escapes the allowed root', async () => {
+    await expect(resolveLocalImagePath(path.join(allowedRoot, 'escape.txt'))).rejects.toThrow(
+      /symlink escapes/
+    );
+  });
+
+  it('rejects a non-existent file', async () => {
+    await expect(resolveLocalImagePath(path.join(allowedRoot, 'nope.png'))).rejects.toThrow(
+      /does not exist/
+    );
+  });
+});
+
+describe('decodeBase64ToTempFile', () => {
+  it('decodes a plain base64 string to a temp file', async () => {
+    const payload = Buffer.from('hello png');
+    const out = await decodeBase64ToTempFile(payload.toString('base64'), 'image/png');
+    try {
+      expect(path.extname(out)).toBe('.png');
+      const written = await fs.readFile(out);
+      expect(written.equals(payload)).toBe(true);
+    } finally {
+      await fs.unlink(out).catch(() => {});
+    }
+  });
+
+  it('accepts a full data: URI and ignores the prefix', async () => {
+    const payload = Buffer.from('svg-bytes');
+    const dataUri = `data:image/svg+xml;base64,${payload.toString('base64')}`;
+    const out = await decodeBase64ToTempFile(dataUri, 'image/svg+xml');
+    try {
+      expect(path.extname(out)).toBe('.svg');
+      const written = await fs.readFile(out);
+      expect(written.equals(payload)).toBe(true);
+    } finally {
+      await fs.unlink(out).catch(() => {});
+    }
+  });
+
+  it('rejects a payload larger than the 5MB cap', async () => {
+    const big = Buffer.alloc(MAX_BASE64_BYTES + 1, 0x41);
+    await expect(decodeBase64ToTempFile(big.toString('base64'), 'image/png')).rejects.toThrow(
+      /exceeds the 5MB/
+    );
+  });
+
+  it('rejects an unsupported mimeType', async () => {
+    const payload = Buffer.from('x');
+    await expect(
+      decodeBase64ToTempFile(payload.toString('base64'), 'application/zip')
+    ).rejects.toThrow(/Unsupported mimeType/);
+  });
+
+  it('rejects invalid base64 input', async () => {
+    await expect(decodeBase64ToTempFile('not base64 at all!!!', 'image/png')).rejects.toThrow(
+      /Invalid base64/
+    );
+  });
+
+  it('maps image/jpeg to .jpg extension', async () => {
+    const payload = Buffer.from([0xff, 0xd8, 0xff]);
+    const out = await decodeBase64ToTempFile(payload.toString('base64'), 'image/jpeg');
+    try {
+      expect(path.extname(out)).toBe('.jpg');
+    } finally {
+      await fs.unlink(out).catch(() => {});
+    }
+  });
+});