mojulo 0.0.0 → 0.1.0

package/lib/mcp/tools/operate.js

@@ -0,0 +1,314 @@
+/**
+ * MCP Ring 2 — operate / read tools.
+ *
+ * Lets the user's Claude reason over deployed bot state without exposing new
+ * HTTP endpoints from the control plane. Reads either hit local SQLite
+ * (deployment metadata) or pass through bot-proxy to the bot's own SQLite
+ * (conversations, submissions, chain verification) — preserving the
+ * "conversation data never leaves the bot's SQLite" invariant.
+ */
+
+import { DeploymentRepository } from '@/lib/db/repositories/deployments';
+import { fetchFromBot } from '@/lib/deployers/bot-proxy';
+import { registerTool } from '@/lib/mcp/server';
+
+function summarizeDeployment(d) {
+  if (!d) return null;
+  return {
+    id: d.id,
+    botName: d.botName,
+    status: d.status,
+    url: d.url || null,
+    lastSeenAt: d.lastSeenAt ? d.lastSeenAt.toISOString() : null,
+    configHash: d.configHash || null,
+    lastBuiltHash: d.lastBuiltHash || null,
+    ragMode: d.ragMode,
+    embeddingChunkCount: d.embeddingChunkCount,
+    cloud: d.cloudProvider
+      ? {
+          provider: d.cloudProvider,
+          status: d.cloudStatus,
+          url: d.cloudUrl,
+          appName: d.cloudAppName,
+          lastDeployedAt: d.cloudLastDeployedAt ? d.cloudLastDeployedAt.toISOString() : null,
+        }
+      : null,
+    createdAt: d.createdAt.toISOString(),
+    updatedAt: d.updatedAt.toISOString(),
+  };
+}
+
+async function listDeploymentsHandler(input, _ctx) {
+  const { status, mode, limit = 50, offset = 0 } = input || {};
+  const all = await DeploymentRepository.list();
+  let filtered = all;
+  if (status) {
+    filtered = filtered.filter((d) => d.status === status);
+  }
+  if (mode === 'cloud') {
+    filtered = filtered.filter((d) => !!d.cloudProvider);
+  } else if (mode === 'local') {
+    filtered = filtered.filter((d) => !d.cloudProvider);
+  }
+  const total = filtered.length;
+  const page = filtered.slice(offset, offset + limit).map(summarizeDeployment);
+  return { total, limit, offset, deployments: page };
+}
+
+function redactConfigCredentials(config) {
+  if (!config || typeof config !== 'object') return config;
+  const llmConfig = config.llmConfig;
+  if (!llmConfig || typeof llmConfig !== 'object') return config;
+  const redactedLlm = {};
+  for (const [provider, providerConfig] of Object.entries(llmConfig)) {
+    if (!providerConfig || typeof providerConfig !== 'object') {
+      redactedLlm[provider] = providerConfig;
+      continue;
+    }
+    const next = { ...providerConfig };
+    if ('apiKey' in next) next.apiKey = next.apiKey ? '[redacted]' : '';
+    if ('accessKeyId' in next && next.accessKeyId) next.accessKeyId = '[redacted]';
+    if ('secretAccessKey' in next && next.secretAccessKey) next.secretAccessKey = '[redacted]';
+    redactedLlm[provider] = next;
+  }
+  return { ...config, llmConfig: redactedLlm };
+}
+
+async function getDeploymentHandler(input, _ctx) {
+  const { id } = input || {};
+  if (!id) throw new Error('id is required');
+  const dep = await DeploymentRepository.findById(id);
+  if (!dep) throw new Error(`Deployment not found: ${id}`);
+  const summary = summarizeDeployment(dep);
+  return {
+    ...summary,
+    config: redactConfigCredentials(dep.config),
+    botSummary: dep.config?.botSummary || null,
+    documentIds: dep.documentIds,
+  };
+}
+
+async function loadConnectedDeployment(id) {
+  if (!id) throw new Error('id is required');
+  const dep = await DeploymentRepository.findById(id);
+  if (!dep) throw new Error(`Deployment not found: ${id}`);
+  if (!dep.url) throw new Error(`Deployment ${id} has no URL — bot is not connected`);
+  return dep;
+}
+
+async function proxyJson(dep, path, opts) {
+  let response;
+  try {
+    response = await fetchFromBot(dep, path, opts);
+  } catch (err) {
+    throw new Error(`Could not reach bot: ${err.message || err.name}`);
+  }
+  if (!response.ok) {
+    const text = await response.text().catch(() => '');
+    throw new Error(
+      `Bot returned ${response.status}: ${text.slice(0, 200)}`
+    );
+  }
+  await DeploymentRepository.touchLastSeen(dep.id).catch(() => {});
+  return response.json();
+}
+
+// Both list and full-dump flows hit /api/conversations/export rather than
+// /api/conversations. The list endpoint has a guardrail that returns 0 rows
+// unless conversationId / startDate / endDate is provided, which surfaced as
+// "0 results but the bot clearly has conversations" through MCP.
+async function fetchExport(dep, { startDate, endDate }) {
+  const qs = new URLSearchParams();
+  if (startDate) qs.set('startDate', String(startDate));
+  if (endDate) qs.set('endDate', String(endDate));
+  const path = `/api/conversations/export${qs.toString() ? `?${qs.toString()}` : ''}`;
+  return proxyJson(dep, path, { timeoutMs: 60000 });
+}
+
+async function queryConversationsHandler(input, _ctx) {
+  const { id, since, until } = input || {};
+  const dep = await loadConnectedDeployment(id);
+  const data = await fetchExport(dep, { startDate: since, endDate: until });
+  const conversations = (Array.isArray(data) ? data : []).map((c) => ({
+    conversationId: c.conversationId,
+    startedAt: c.startedAt,
+    lastActivity: c.lastActivity,
+    turnCount: c.turnCount,
+  }));
+  return { botName: dep.botName, total: conversations.length, conversations };
+}
+
+// The bot's /api/conversations/:id endpoint emits raw snake_case columns, while
+// /api/conversations/export hand-maps to camelCase. Normalize the by-id turn
+// shape so consumers see one casing across both tools.
+function normalizeTurn(t) {
+  if (!t || typeof t !== 'object') return t;
+  return {
+    id: t.id,
+    conversationId: t.conversation_id,
+    turn: t.turn,
+    timestamp: t.timestamp,
+    userPrompt: t.user_prompt,
+    llmResponse: t.llm_response,
+    machineState: t.machine_state,
+    ragContext: t.rag_context,
+    contentHash: t.content_hash,
+    chainHash: t.chain_hash,
+    eventType: t.event_type,
+    handoffHash: t.handoff_hash,
+  };
+}
+
+async function getConversationHandler(input, _ctx) {
+  const { id, conversationId } = input || {};
+  if (!conversationId) throw new Error('conversationId is required');
+  const dep = await loadConnectedDeployment(id);
+  const data = await proxyJson(dep, `/api/conversations/${encodeURIComponent(conversationId)}`);
+  return {
+    ...data,
+    turns: Array.isArray(data?.turns) ? data.turns.map(normalizeTurn) : data?.turns,
+  };
+}
+
+async function exportConversationsHandler(input, _ctx) {
+  const { id, startDate, endDate } = input || {};
+  const dep = await loadConnectedDeployment(id);
+  const data = await fetchExport(dep, { startDate, endDate });
+  return { botName: dep.botName, conversations: data };
+}
+
+async function querySubmissionsHandler(input, _ctx) {
+  const { id, limit, offset, since, until } = input || {};
+  const dep = await loadConnectedDeployment(id);
+  const qs = new URLSearchParams();
+  if (limit != null) qs.set('limit', String(limit));
+  if (offset != null) qs.set('offset', String(offset));
+  if (since) qs.set('since', String(since));
+  if (until) qs.set('until', String(until));
+  const path = `/api/forms${qs.toString() ? `?${qs.toString()}` : ''}`;
+  const data = await proxyJson(dep, path);
+  return { botName: dep.botName, ...data };
+}
+
+async function verifyChainHandler(input, _ctx) {
+  const { id, conversationId } = input || {};
+  if (!conversationId) throw new Error('conversationId is required');
+  const dep = await loadConnectedDeployment(id);
+  return proxyJson(dep, `/verify/${encodeURIComponent(conversationId)}`);
+}
+
+export function registerOperateTools() {
+  // Deployment metadata — always available. No transcript data, just rows
+  // from the control plane's deployments table.
+  registerTool({
+    name: 'list_deployments',
+    description:
+      'List bots known to the control plane. Returns id, name, status, URL, connection state, and cloud metadata. Filter by status (saved | building | ready | stale | build_failed) or mode (local | cloud).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: { type: 'string', description: 'Filter by deployment status.' },
+        mode: { type: 'string', enum: ['local', 'cloud'], description: 'Filter by local-only or cloud-deployed bots.' },
+        limit: { type: 'integer', minimum: 1, maximum: 200, default: 50 },
+        offset: { type: 'integer', minimum: 0, default: 0 },
+      },
+    },
+    handler: listDeploymentsHandler,
+  });
+
+  registerTool({
+    name: 'get_deployment',
+    description:
+      'Get the full deployment row for one bot: identity, enabled protocols, generated configs, document ids, and cloud state. Reads from the control plane SQLite only — no proxy to the bot.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Deployment id.' },
+      },
+      required: ['id'],
+    },
+    handler: getDeploymentHandler,
+  });
+
+  // Transcript-touching tools. The proxy reads keep conversation data inside
+  // the bot's SQLite — the model sees them but the control-plane DB never does.
+  registerTool({
+    name: 'query_conversations',
+    description:
+      'List conversation summaries on a connected bot (one entry per conversation — id, started_at, last_activity, turn_count). Proxies through to the bot — conversation rows live in the bot SQLite, never the control plane. Optional since / until ISO bounds filter on the first-turn timestamp. Use get_conversation for the full turn list, or export_conversations to pull every turn in one shot.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Deployment id.' },
+        since: { type: 'string', description: 'ISO timestamp lower bound on first-turn timestamp.' },
+        until: { type: 'string', description: 'ISO timestamp upper bound on first-turn timestamp.' },
+      },
+      required: ['id'],
+    },
+    handler: queryConversationsHandler,
+  });
+
+  registerTool({
+    name: 'get_conversation',
+    description:
+      'Get the full turn list for one conversation on a connected bot. Proxies through to the bot.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Deployment id.' },
+        conversationId: { type: 'string', description: 'Conversation id on the bot.' },
+      },
+      required: ['id', 'conversationId'],
+    },
+    handler: getConversationHandler,
+  });
+
+  registerTool({
+    name: 'export_conversations',
+    description:
+      'Bulk export full conversations on a connected bot, including every turn. Optional startDate / endDate ISO bounds filter on the conversation\'s first turn. Returns one entry per conversation with the full turn list nested under each — use sparingly on bots with many conversations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Deployment id.' },
+        startDate: { type: 'string', description: 'ISO timestamp lower bound on first-turn timestamp.' },
+        endDate: { type: 'string', description: 'ISO timestamp upper bound on first-turn timestamp.' },
+      },
+      required: ['id'],
+    },
+    handler: exportConversationsHandler,
+  });
+
+  registerTool({
+    name: 'query_submissions',
+    description:
+      'List form-gathering submissions on a connected bot. Proxies through to the bot.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Deployment id.' },
+        limit: { type: 'integer', minimum: 1, maximum: 200 },
+        offset: { type: 'integer', minimum: 0 },
+        since: { type: 'string' },
+        until: { type: 'string' },
+      },
+      required: ['id'],
+    },
+    handler: querySubmissionsHandler,
+  });
+
+  registerTool({
+    name: 'verify_chain',
+    description:
+      'Walk the tamper-evident hash chain for one conversation. Returns the verification result from the bot. See docs/turn-hashing.md for the chain semantics.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Deployment id.' },
+        conversationId: { type: 'string', description: 'Conversation id on the bot.' },
+      },
+      required: ['id', 'conversationId'],
+    },
+    handler: verifyChainHandler,
+  });
+}

package/lib/preview/build-preview-config.js

@@ -0,0 +1,136 @@
+/**
+ * Map the wizard's in-progress formData into the shape the bot's client
+ * (lite-template/client/index.html) expects from a deployed container's
+ * `/context` endpoint. This is what the preview iframe reads via
+ * `window.__INITIAL_CONFIG__`.
+ *
+ * Production source of truth: mojulo-lite/lite-template/server.js — the
+ * `/` route (line ~186) and `/context` route (line ~963) build the same
+ * object from on-disk config files. We mirror that shape here, but pulled
+ * from React state instead.
+ */
+
+import { buildLLMConfig } from '@/lib/config-builder';
+
+function safeParseFormJson(json) {
+  if (!json) return null;
+  try {
+    return typeof json === 'string' ? JSON.parse(json) : json;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the `botContext` payload from wizard formData + enabledProtocols.
+ * Returns null if the bare-minimum LLM config isn't ready yet (no provider
+ * or no credential) so the preview can show a setup hint instead of booting
+ * a half-configured bot.
+ *
+ * Credential can come in three shapes:
+ *   - formData.apiKey         pasted plaintext (rides in the llm block)
+ *   - formData.apiKeyId       saved-key reference (decrypted server-side at
+ *                             /api/preview/chat — mirrors the deploy path)
+ *   - formData.hasStoredApiKey + formData.editDeploymentId
+ *                             edit mode reusing the existing on-file key:
+ *                             the chat route looks it up from the deployment
+ *                             row server-side. The browser never sees the
+ *                             plaintext.
+ */
+export function buildPreviewConfig(formData, enabledProtocols) {
+  // Ollama is credential-less — provider + model are sufficient to boot
+  // the preview. The host falls back to LLM_PROVIDERS.ollama.defaultHost in
+  // buildLLMConfig when ollamaHost is blank.
+  const isOllama = formData?.provider === 'ollama';
+  const hasCredential = isOllama || Boolean(
+    formData?.apiKey ||
+      formData?.apiKeyId ||
+      (formData?.hasStoredApiKey && formData?.editDeploymentId),
+  );
+  if (!formData?.provider || !hasCredential || !formData?.model) {
+    return null;
+  }
+
+  const llm = buildLLMConfig(formData.provider, formData.apiKey || '', formData.model, {
+    maxTokens: 2048,
+    ollamaHost: formData.ollamaHost,
+  });
+
+  const formStructure = enabledProtocols.formGathering
+    ? safeParseFormJson(formData.generatedFormJson)
+    : null;
+
+  const botContext = {
+    name: formData.botName || 'Preview Bot',
+    chatDisplayName:
+      formData.uiSettings?.chatDisplayName || formData.chatDisplayName || 'Bot',
+    placeholder:
+      formData.uiSettings?.placeholder ||
+      formData.placeholder ||
+      'Type your message...',
+    firstMessage:
+      formData.firstMessage || 'Hello! How can I help you today?',
+    suggestedPrompts: formData.suggestedPrompts || [],
+
+    isForm: Boolean(enabledProtocols.formGathering && formStructure),
+    formStructure: formStructure || undefined,
+    formCompletionWebhook: formData.formCompletionWebhook || '',
+    afterSubmitChatMessage: formData.afterSubmitChatMessage || '',
+    formSendHome: Boolean(formData.formSendHome),
+    termsAndConditions: formData.termsAndConditions || '',
+
+    isCalendar: Boolean(
+      enabledProtocols.appointments &&
+        formData.appointmentDestinations?.length > 0,
+    ),
+    calendarConfig: enabledProtocols.appointments
+      ? formData.appointmentDestinations || []
+      : [],
+
+    isTriage: Boolean(
+      enabledProtocols.triage && formData.triageRoutes?.length > 0,
+    ),
+    triageRoutes: enabledProtocols.triage ? formData.triageRoutes || [] : [],
+
+    isOpticalRead: Boolean(
+      enabledProtocols.opticalRead && formData.opticalReadFields?.length > 0,
+    ),
+    opticalReadFields: enabledProtocols.opticalRead
+      ? formData.opticalReadFields || []
+      : [],
+    opticalReadShowUploadOnStart: Boolean(
+      enabledProtocols.opticalRead && formData.opticalReadShowUploadOnStart,
+    ),
+    opticalReadAfterSubmitMessage: enabledProtocols.opticalRead
+      ? formData.opticalReadAfterSubmitMessage || ''
+      : '',
+  };
+
+  // The shim uses these to translate /chat calls into /api/preview/chat
+  // calls. They aren't part of the deployed bot's /context shape — they
+  // ride along as `__previewMeta` so the production client never sees them.
+  const previewMeta = {
+    objective:
+      formData.objective || `Help users as ${formData.botName || 'a bot'}.`,
+    enabledProtocols,
+    protocolData: {
+      ...(formStructure ? { formStructure } : {}),
+      ...(enabledProtocols.appointments
+        ? { appointments: formData.appointmentDestinations || [] }
+        : {}),
+      ...(enabledProtocols.triage
+        ? { triage: formData.triageRoutes || [] }
+        : {}),
+      ...(enabledProtocols.opticalRead
+        ? { opticalRead: { fields: formData.opticalReadFields || [] } }
+        : {}),
+    },
+    llm,
+    apiKeyId: formData.apiKeyId || null,
+    editDeploymentId: formData.editDeploymentId || null,
+    documentIds: (formData.documents || []).map((d) => d.id),
+    embeddingsStorageKey: formData.embeddings?.storageKey || null,
+  };
+
+  return { botContext, previewMeta };
+}

package/lib/rate-limiter.js

@@ -0,0 +1,11 @@
+// Lite runs locally for a single operator — no need to rate-limit ourselves.
+// Keep the shape the copied stream route expects.
+
+export const RateLimitPresets = {
+  expensive: { windowMs: 60_000, max: 60 },
+  default: { windowMs: 60_000, max: 300 },
+};
+
+export function checkRateLimit(_request, _options) {
+  return { allowed: true };
+}

package/lib/resolve-api-key.js

@@ -0,0 +1,142 @@
+import { ApiKeyRepository } from './db/repositories/apiKeys.js';
+import { decryptApiKey } from './deployment-auth.js';
+import { buildBedrockModelId } from './llm-providers.js';
+
+/**
+ * Inject a saved (encrypted) provider credential into a deployment config so
+ * the browser never has to handle plaintext when picking a saved key. The
+ * wizard sends apiKeyId; the route hands the deployment config + id here, and
+ * we patch config.llm[provider] in place. Throws if the id is unknown or its
+ * provider doesn't match config.llm.provider — both indicate a stale UI state
+ * worth surfacing.
+ */
+export async function resolveSavedApiKeyIntoConfig(config, apiKeyId) {
+  if (!apiKeyId || !config?.llm?.provider) return config;
+
+  const record = await ApiKeyRepository.findById(apiKeyId);
+  if (!record) {
+    throw new Error(`Saved API key ${apiKeyId} not found`);
+  }
+
+  const provider = config.llm.provider;
+  if (record.provider !== provider) {
+    throw new Error(
+      `Saved API key provider "${record.provider}" does not match selected provider "${provider}"`
+    );
+  }
+
+  const plaintext = decryptApiKey(record.encryptedKey);
+
+  if (provider === 'bedrock') {
+    const credentials = JSON.parse(plaintext);
+    const region = credentials.region || 'us-east-1';
+    const baseModel = config.llm.bedrock?.model || '';
+    config.llm.bedrock = {
+      ...config.llm.bedrock,
+      region,
+      useIamRole: credentials.useIamRole || false,
+      accessKeyId: credentials.accessKeyId || null,
+      secretAccessKey: credentials.secretAccessKey || null,
+      model: buildBedrockModelId(baseModel, region),
+    };
+  } else if (provider === 'ollama') {
+    // Ollama's "credential" row stores {"host": "..."} JSON. The host stamps
+    // onto config.llm.ollama just like buildLLMConfig would have done from
+    // the wizard's ollamaHost field — saved-host references and pasted
+    // hosts converge on the same artifact shape.
+    const parsed = JSON.parse(plaintext);
+    config.llm.ollama = {
+      ...config.llm.ollama,
+      host: parsed.host || config.llm.ollama?.host || '',
+    };
+  } else {
+    config.llm[provider] = {
+      ...config.llm[provider],
+      apiKey: plaintext,
+    };
+  }
+
+  return config;
+}
+
+/**
+ * Whether a deployment config currently carries a usable provider credential
+ * for its selected provider. Computed against the un-redacted config so the
+ * GET endpoint can advertise "key on file" without exposing the value. The
+ * wizard reads this to gate the credential requirement in edit mode.
+ */
+export function configHasStoredApiKey(config) {
+  const provider = config?.llm?.provider;
+  if (!provider) return false;
+  const block = config.llm[provider];
+  if (!block) return false;
+  if (provider === 'bedrock') {
+    return !!(block.useIamRole || (block.accessKeyId && block.secretAccessKey));
+  }
+  if (provider === 'ollama') {
+    // Host is the only transport field. Empty host means the wizard will
+    // fall back to LLM_PROVIDERS.ollama.defaultHost at build time, which is
+    // still a usable artifact — but the "on file" claim should be honest
+    // about whether the user actually configured one.
+    return !!block.host;
+  }
+  return !!block.apiKey;
+}
+
+/**
+ * Strip provider credentials from a deployment config before returning it
+ * to the browser. The deployment row stores plaintext (it's what gets baked
+ * into the artifact's .env), but edit-mode hydration shouldn't have to
+ * surface it to populate the wizard. Operates on a clone — caller's object
+ * is not mutated.
+ */
+export function redactApiKeysFromConfig(config) {
+  if (!config?.llm) return config;
+  const clone = structuredClone(config);
+  for (const key of Object.keys(clone.llm)) {
+    if (key === 'provider') continue;
+    const block = clone.llm[key];
+    if (!block || typeof block !== 'object') continue;
+    if ('apiKey' in block) block.apiKey = '';
+    if ('accessKeyId' in block) block.accessKeyId = null;
+    if ('secretAccessKey' in block) block.secretAccessKey = null;
+  }
+  return clone;
+}
+
+/**
+ * When PATCH'ing an existing deployment without a fresh credential — the
+ * wizard hydrated from the redacted GET and the user didn't paste/pick a
+ * new key — copy the previously-stored credentials forward so the artifact
+ * keeps working. Mutates newConfig in place. Provider-switch is detected by
+ * comparing llm.provider; on switch we don't carry credentials across.
+ */
+export function preserveExistingCredentials(newConfig, oldConfig) {
+  const provider = newConfig?.llm?.provider;
+  if (!provider || !oldConfig?.llm) return newConfig;
+  if (oldConfig.llm.provider !== provider) return newConfig;
+
+  const newBlock = newConfig.llm[provider];
+  const oldBlock = oldConfig.llm[provider];
+  if (!newBlock || !oldBlock) return newConfig;
+
+  if (provider === 'bedrock') {
+    const newHasCreds = newBlock.useIamRole || (newBlock.accessKeyId && newBlock.secretAccessKey);
+    if (!newHasCreds) {
+      newBlock.useIamRole = oldBlock.useIamRole;
+      newBlock.accessKeyId = oldBlock.accessKeyId;
+      newBlock.secretAccessKey = oldBlock.secretAccessKey;
+      newBlock.region = newBlock.region || oldBlock.region;
+    }
+  } else if (provider === 'ollama') {
+    // Ollama carries host instead of a credential. Edit mode that doesn't
+    // re-submit a host should keep the previously stored one.
+    if (!newBlock.host) {
+      newBlock.host = oldBlock.host || '';
+    }
+  } else if (!newBlock.apiKey) {
+    newBlock.apiKey = oldBlock.apiKey || '';
+  }
+
+  return newConfig;
+}

package/lib/storage/index.js

@@ -0,0 +1,40 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+const STORAGE_ROOT =
+  process.env.STORAGE_ROOT || path.join(process.cwd(), 'data', 'storage');
+
+function resolveStoragePath(key) {
+  // Prevent traversal escape
+  const safe = key.replace(/^\/+/, '').replace(/\.\./g, '_');
+  return path.join(STORAGE_ROOT, safe);
+}
+
+async function ensureDir(filePath) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+}
+
+export async function uploadFile(key, buffer, _legacyIgnored, _opts = {}) {
+  const dest = resolveStoragePath(key);
+  await ensureDir(dest);
+  await fs.writeFile(dest, buffer);
+  return { storagePath: key };
+}
+
+export async function downloadToBuffer(key) {
+  const source = resolveStoragePath(key);
+  return fs.readFile(source);
+}
+
+export async function deleteFile(key) {
+  const target = resolveStoragePath(key);
+  try {
+    await fs.unlink(target);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+}
+
+export function getStorageRoot() {
+  return STORAGE_ROOT;
+}