@cheapbuddy/media-mcp 0.0.0-stage → 0.1.0

package/src/errors.mjs

@@ -0,0 +1,98 @@
+const SECRET_PATTERNS = [
+  /Bearer\s+[A-Za-z0-9._~+\/-]+=*/gi,
+  /(?:api[_-]?key|authorization|token|secret|password)\s*[:=]\s*[^\s,;]+/gi,
+];
+
+export class MediaMcpError extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = "MediaMcpError";
+    this.code = code;
+    this.status = options.status;
+    this.retryAfterMs = options.retryAfterMs;
+    this.retryable = options.retryable === true;
+    this.ambiguous = options.ambiguous === true;
+    this.details = options.details;
+    this.cause = options.cause;
+  }
+}
+
+export function redactSecrets(value) {
+  let text = String(value ?? "");
+  for (const pattern of SECRET_PATTERNS) {
+    text = text.replace(pattern, (match) => {
+      const separator = match.indexOf("=") >= 0 ? "=" : ":";
+      return match.slice(0, Math.max(0, match.indexOf(separator) + 1)) + "[redacted]";
+    });
+  }
+  return text.replace(/https?:\/\/[^\s/]+\/[^\s]*/gi, (url) => {
+    try {
+      const parsed = new URL(url);
+      parsed.username = "";
+      parsed.password = "";
+      for (const key of ["key", "token", "signature", "sig", "secret"]) {
+        if (parsed.searchParams.has(key)) parsed.searchParams.set(key, "[redacted]");
+      }
+      return parsed.toString();
+    } catch {
+      return "[redacted-url]";
+    }
+  });
+}
+
+export function publicError(error) {
+  if (error instanceof MediaMcpError) {
+    return {
+      code: error.code,
+      message: redactSecrets(error.message),
+      ...(error.details === undefined ? {} : { details: error.details }),
+      ...(error.retryAfterMs === undefined ? {} : { retry_after_ms: error.retryAfterMs }),
+    };
+  }
+  return {
+    code: "internal_error",
+    message: "CheapBuddy Media MCP could not complete the request.",
+  };
+}
+
+export function validationError(message, details) {
+  return new MediaMcpError("invalid_request", message, { details });
+}
+
+export function configurationError(message) {
+  return new MediaMcpError("configuration_error", message);
+}
+
+export function httpError(status, message, options = {}) {
+  const retryAfterMs = options.retryAfterMs;
+  return new MediaMcpError(options.code || httpCode(status), message, {
+    status,
+    retryAfterMs,
+    retryable: options.retryable,
+    ambiguous: options.ambiguous,
+    details: options.details,
+  });
+}
+
+function httpCode(status) {
+  if (status === 401 || status === 403) return "authentication_error";
+  if (status === 404) return "not_found";
+  if (status === 409) return "idempotency_conflict";
+  if (status === 429) return "rate_limited";
+  if (status >= 500) return "upstream_error";
+  return "request_failed";
+}
+
+export function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw validationError(`${name} must be an object.`);
+  }
+  return value;
+}
+
+export function assertNoUnknownKeys(value, allowed, name = "request") {
+  for (const key of Object.keys(value || {})) {
+    if (!allowed.has(key)) throw validationError(`${name} contains unsupported field: ${key}.`);
+  }
+}
+

package/src/http.mjs

@@ -0,0 +1,168 @@
+import { randomUUID } from "node:crypto";
+import { configurationError, httpError, MediaMcpError, redactSecrets } from "./errors.mjs";
+
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+const READ_RETRY_DELAYS = [250, 750];
+
+export class CheapBuddyHttpClient {
+  constructor(options = {}) {
+    const apiKey = String(options.apiKey ?? process.env.CHEAPBUDDY_API_KEY ?? "").trim();
+    if (!apiKey) throw configurationError("CHEAPBUDDY_API_KEY is required.");
+    if (apiKey.length > 4096 || /[\r\n]/u.test(apiKey)) throw configurationError("CHEAPBUDDY_API_KEY is invalid.");
+    this.apiKey = apiKey;
+    this.baseUrl = normalizeBaseUrl(options.baseUrl || process.env.CHEAPBUDDY_BASE_URL || "https://api.cheapbuddy.cc");
+    this.fetchImpl = options.fetchImpl || globalThis.fetch;
+    if (typeof this.fetchImpl !== "function") throw configurationError("This Node.js runtime does not provide fetch.");
+    this.timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(1000, options.timeoutMs) : 60000;
+    this.sleep = options.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.requestId = options.requestId || (() => randomUUID());
+  }
+
+  async json(method, path, body, options = {}) {
+    return this.request(method, path, { ...options, body, json: true });
+  }
+
+  async readJson(method, path, options = {}) {
+    let attempt = 0;
+    while (true) {
+      try {
+        return await this.request(method, path, options);
+      } catch (error) {
+        if (!shouldRetryRead(error) || attempt >= READ_RETRY_DELAYS.length) throw error;
+        const delay = error.retryAfterMs ?? READ_RETRY_DELAYS[attempt];
+        attempt += 1;
+        await this.sleep(Math.min(Math.max(delay, 0), 10000));
+      }
+    }
+  }
+
+  async uploadMedia(bytes, mimeType, options = {}) {
+    if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array)) throw new TypeError("bytes must be binary data");
+    return this.request("POST", "/v1/media", {
+      body: bytes,
+      contentType: mimeType,
+      ...options,
+    });
+  }
+
+  async request(method, requestPath, options = {}) {
+    const url = this.buildUrl(requestPath);
+    const headers = new Headers(options.headers || {});
+    headers.set("Accept", "application/json");
+    headers.set("Authorization", `Bearer ${this.apiKey}`);
+    headers.set("X-Request-ID", this.requestId());
+    if (options.idempotencyKey) headers.set("Idempotency-Key", options.idempotencyKey);
+    let body = options.body;
+    if (options.json) {
+      headers.set("Content-Type", "application/json");
+      body = JSON.stringify(body ?? {});
+    } else if (options.contentType) {
+      headers.set("Content-Type", options.contentType);
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs || this.timeoutMs);
+    let response;
+    try {
+      response = await this.fetchImpl(url, { method, headers, body, signal: controller.signal });
+    } catch (error) {
+      throw new MediaMcpError("network_error", "CheapBuddy Relay could not be reached.", {
+        retryable: method === "GET" || method === "HEAD",
+        ambiguous: method !== "GET" && method !== "HEAD",
+        cause: error,
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+    const text = await readBoundedText(response);
+    const payload = parsePayload(text, response.headers.get("content-type"));
+    if (!response.ok) {
+      const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+      const message = safeRemoteMessage(payload, response.status);
+      throw httpError(response.status, message, {
+        retryAfterMs,
+        retryable: response.status === 429 || response.status >= 500,
+        ambiguous: response.status >= 500 && method !== "GET" && method !== "HEAD",
+        code: payload?.error?.type || undefined,
+        details: { status: response.status },
+      });
+    }
+    return payload;
+  }
+
+  buildUrl(requestPath) {
+    if (typeof requestPath !== "string" || !requestPath.startsWith("/")) throw new Error("Relay path must be absolute.");
+    return new URL(requestPath, this.baseUrl).toString();
+  }
+}
+
+export function normalizeBaseUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(String(value));
+  } catch {
+    throw configurationError("CHEAPBUDDY_BASE_URL is invalid.");
+  }
+  if (!/^https?:$/u.test(parsed.protocol) || parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw configurationError("CHEAPBUDDY_BASE_URL must be an HTTP(S) origin without credentials or query parameters.");
+  }
+  return parsed.toString().replace(/\/$/u, "");
+}
+
+async function readBoundedText(response) {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) throw new MediaMcpError("response_too_large", "Relay response exceeded the safety limit.");
+  if (!response.body?.getReader) {
+    const text = await response.text();
+    if (Buffer.byteLength(text, "utf8") > MAX_RESPONSE_BYTES) throw new MediaMcpError("response_too_large", "Relay response exceeded the safety limit.");
+    return text;
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > MAX_RESPONSE_BYTES) {
+        await reader.cancel();
+        throw new MediaMcpError("response_too_large", "Relay response exceeded the safety limit.");
+      }
+      chunks.push(Buffer.from(value));
+    }
+  } finally {
+    reader.releaseLock?.();
+  }
+  return Buffer.concat(chunks, total).toString("utf8");
+}
+
+function parsePayload(text, contentType) {
+  if (!text) return {};
+  if (String(contentType || "").includes("json") || /^[\s]*[\[{]/u.test(text)) {
+    try { return JSON.parse(text); } catch { return { error: { message: "Relay returned malformed JSON." } }; }
+  }
+  return { raw: text.slice(0, 512) };
+}
+
+function safeRemoteMessage(payload, status) {
+  const candidate = payload?.error?.message || payload?.message || payload?.error || `Relay request failed with HTTP ${status}.`;
+  const message = redactSecrets(typeof candidate === "string" ? candidate : "Relay request failed.")
+    .replace(/https?:\/\/[^\s)]+/giu, "[redacted-url]");
+  return message.length > 500 ? message.slice(0, 500) : message;
+}
+
+function parseRetryAfter(value) {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, 10000);
+  const date = Date.parse(value);
+  if (Number.isFinite(date)) return Math.min(Math.max(date - Date.now(), 0), 10000);
+  return undefined;
+}
+
+function shouldRetryRead(error) {
+  return error instanceof MediaMcpError && (error.retryable === true || error.code === "rate_limited") && !error.ambiguous;
+}
+
+export { MAX_RESPONSE_BYTES };
+

package/src/job-id.mjs

@@ -0,0 +1,34 @@
+import { validationError } from "./errors.mjs";
+
+const PREFIXES = Object.freeze({ image: "img_task_", video: "vid_task_" });
+
+export function encodeJobId(kind, taskId) {
+  const prefix = PREFIXES[kind];
+  const value = String(taskId ?? "").trim();
+  if (!prefix || !value || value.length > 512 || /[\u0000-\u001f\u007f]/u.test(value)) {
+    throw new Error("Relay returned an invalid task identity.");
+  }
+  return prefix + Buffer.from(value, "utf8").toString("base64url");
+}
+
+export function decodeJobId(value) {
+  const input = String(value ?? "");
+  const entry = Object.entries(PREFIXES).find(([, prefix]) => input.startsWith(prefix));
+  if (!entry) throw validationError("job_id must be an MCP-generated media job ID.");
+  const [kind, prefix] = entry;
+  const encoded = input.slice(prefix.length);
+  if (!encoded || !/^[A-Za-z0-9_-]+$/.test(encoded) || encoded.length > 700) {
+    throw validationError("job_id is invalid.");
+  }
+  let taskId;
+  try {
+    taskId = Buffer.from(encoded, "base64url").toString("utf8");
+  } catch {
+    throw validationError("job_id is invalid.");
+  }
+  if (!taskId || taskId.length > 512 || /[\u0000-\u001f\u007f]/u.test(taskId) || Buffer.from(taskId, "utf8").toString("base64url") !== encoded) {
+    throw validationError("job_id is invalid.");
+  }
+  return { kind, taskId };
+}
+

package/src/media-input.mjs

@@ -0,0 +1,181 @@
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import net from "node:net";
+import { validationError } from "./errors.mjs";
+
+export const MEDIA_LIMITS = Object.freeze({
+  image: { maxBytes: 30 * 1024 * 1024, aggregateBytes: 60 * 1024 * 1024 },
+  video: { maxBytes: 50 * 1024 * 1024, aggregateBytes: 60 * 1024 * 1024 },
+  audio: { maxBytes: 15 * 1024 * 1024, aggregateBytes: 60 * 1024 * 1024 },
+});
+
+const EXTENSIONS = Object.freeze({
+  ".png": ["image/png", "image"],
+  ".jpg": ["image/jpeg", "image"],
+  ".jpeg": ["image/jpeg", "image"],
+  ".webp": ["image/webp", "image"],
+  ".gif": ["image/gif", "image"],
+  ".heic": ["image/heic", "image"],
+  ".heif": ["image/heif", "image"],
+  ".mp4": ["video/mp4", "video"],
+  ".m4v": ["video/mp4", "video"],
+  ".mov": ["video/quicktime", "video"],
+  ".webm": ["video/webm", "video"],
+  ".wav": ["audio/wav", "audio"],
+  ".mp3": ["audio/mpeg", "audio"],
+  ".m4a": ["audio/mp4", "audio"],
+  ".aac": ["audio/aac", "audio"],
+  ".ogg": ["audio/ogg", "audio"],
+});
+
+const BLOCKED_HOSTNAMES = new Set([
+  "localhost",
+  "localhost.localdomain",
+  "metadata.google.internal",
+  "metadata.google.com",
+  "instance-data.ec2.internal",
+]);
+
+const FILE_IO_LIMIT = 4;
+let activeFileReads = 0;
+const pendingFileReads = [];
+
+export function validateMediaInput(value, expectedKind, options = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw validationError(`${expectedKind} input must contain exactly one path or url.`);
+  }
+  const keys = Object.keys(value);
+  if (keys.length !== 1 || (!keys.includes("path") && !keys.includes("url"))) {
+    throw validationError(`${expectedKind} input must contain exactly one path or url.`);
+  }
+  if (value.path !== undefined) {
+    if (typeof value.path !== "string" || value.path.length > 4096 || !path.isAbsolute(value.path)) {
+      throw validationError("Local media paths must be absolute.");
+    }
+    return { kind: "path", path: value.path, expectedKind, ...options };
+  }
+  if (typeof value.url !== "string" || value.url.length > 8192) throw validationError("Media URL must be a string of at most 8192 characters.");
+  return { kind: "url", url: validateHttpsUrl(value.url), expectedKind, ...options };
+}
+
+export function validateHttpsUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw validationError("Media URL is invalid.");
+  }
+  if (parsed.protocol !== "https:") throw validationError("Media URL must use HTTPS.");
+  if (parsed.username || parsed.password) throw validationError("Media URL must not contain credentials.");
+  const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (BLOCKED_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost") || hostname.endsWith(".local")) {
+    throw validationError("Media URL points to a private or local host.");
+  }
+  if (net.isIP(hostname) && isPrivateAddress(hostname)) {
+    throw validationError("Media URL points to a private or metadata address.");
+  }
+  return parsed.toString();
+}
+
+export function isPrivateAddress(hostname) {
+  const version = net.isIP(hostname);
+  if (version === 4) {
+    const parts = hostname.split(".").map(Number);
+    return parts[0] === 0 || parts[0] === 10 || parts[0] === 127 ||
+      (parts[0] === 169 && parts[1] === 254) ||
+      (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) ||
+      (parts[0] === 192 && parts[1] === 168);
+  }
+  if (version === 6) {
+    const normalized = hostname.toLowerCase();
+    return normalized === "::1" || normalized === "::" || normalized.startsWith("fc") ||
+      normalized.startsWith("fd") || normalized.startsWith("fe8") || normalized.startsWith("fe9") ||
+      normalized.startsWith("fea") || normalized.startsWith("feb");
+  }
+  return false;
+}
+
+export async function loadLocalMedia(input, expectedKind, options = {}) {
+  if (input?.kind === "url" && input.expectedKind === expectedKind && typeof input.url === "string") return input;
+  if (input?.kind === "file" && input.mediaKind === expectedKind && Buffer.isBuffer(input.bytes)) return input;
+  if (input?.kind === "path" && input.expectedKind === expectedKind && typeof input.path === "string") input = { path: input.path };
+  const validated = validateMediaInput(input, expectedKind, options);
+  if (validated.kind === "url") return validated;
+  await acquireFileSlot();
+  try {
+    const info = await lstat(validated.path).catch(() => {
+      throw validationError("Local media file does not exist or is not accessible.");
+    });
+    if (info.isSymbolicLink()) throw validationError("Symbolic-link media inputs are not allowed.");
+    if (!info.isFile()) throw validationError("Media input must be a regular file.");
+    const extension = path.extname(validated.path).toLowerCase();
+    const descriptor = EXTENSIONS[extension];
+    if (!descriptor || descriptor[1] !== expectedKind) {
+      throw validationError(`Unsupported ${expectedKind} file type.`);
+    }
+    const limits = MEDIA_LIMITS[expectedKind];
+    if (info.size > limits.maxBytes) throw validationError(`${expectedKind} input exceeds the per-file size limit.`);
+    const bytes = await readFile(validated.path);
+    if (bytes.length !== info.size) throw validationError("Media file changed while it was being read.");
+    if (!looksLikeKind(bytes, expectedKind, descriptor[0])) throw validationError("Media file content does not match its declared type.");
+    return {
+      kind: "file",
+      path: validated.path,
+      filename: path.basename(validated.path),
+      mimeType: descriptor[0],
+      mediaKind: expectedKind,
+      bytes,
+    };
+  } finally {
+    releaseFileSlot();
+  }
+}
+
+export function validateAggregate(inputs, expectedKind) {
+  const total = inputs.filter((item) => item?.kind === "file").reduce((sum, item) => sum + item.bytes.length, 0);
+  if (total > MEDIA_LIMITS[expectedKind].aggregateBytes) throw validationError(`${expectedKind} inputs exceed the aggregate size limit.`);
+}
+
+function looksLikeKind(bytes, kind, mime) {
+  if (bytes.length === 0) return false;
+  if (kind === "image") {
+    if (mime === "image/png") return bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+    if (mime === "image/jpeg") return bytes.subarray(0, 3).equals(Buffer.from([255, 216, 255]));
+    if (mime === "image/webp") return bytes.subarray(0, 4).toString("ascii") === "RIFF" && bytes.subarray(8, 12).toString("ascii") === "WEBP";
+    if (mime === "image/gif") return ["GIF87a", "GIF89a"].includes(bytes.subarray(0, 6).toString("ascii"));
+    return bytes.subarray(4, 8).toString("ascii") === "ftyp";
+  }
+  if (kind === "video") {
+    if (mime === "video/webm") return bytes.subarray(0, 4).equals(Buffer.from([0x1a, 0x45, 0xdf, 0xa3]));
+    return bytes.length > 12 && bytes.subarray(4, 8).toString("ascii") === "ftyp";
+  }
+  if (mime === "audio/wav") return bytes.subarray(0, 4).toString("ascii") === "RIFF" && bytes.subarray(8, 12).toString("ascii") === "WAVE";
+  if (mime === "audio/mpeg") return bytes.subarray(0, 3).toString("ascii") === "ID3" || (bytes[0] === 0xff && (bytes[1] & 0xe0) === 0xe0);
+  if (mime === "audio/ogg") return bytes.subarray(0, 4).toString("ascii") === "OggS";
+  return bytes.subarray(4, 8).toString("ascii") === "ftyp" || bytes.subarray(0, 4).toString("ascii") === "ADIF";
+}
+
+export function inputValue(input) {
+  if (input.kind === "url") return input.url;
+  return input.bytes;
+}
+
+export function fileIoStats() {
+  return { active: activeFileReads, pending: pendingFileReads.length, limit: FILE_IO_LIMIT };
+}
+
+async function acquireFileSlot() {
+  if (activeFileReads < FILE_IO_LIMIT) {
+    activeFileReads += 1;
+    return;
+  }
+  await new Promise((resolve) => pendingFileReads.push(resolve));
+  activeFileReads += 1;
+}
+
+function releaseFileSlot() {
+  activeFileReads = Math.max(0, activeFileReads - 1);
+  const next = pendingFileReads.shift();
+  if (next) next();
+}
+