@yunsoft/yuncms-api 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunsoft/yuncms-api",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Express API runtime and bundled Studio server for YunCMS.",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
     "@modelcontextprotocol/node": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
     "@node-saml/node-saml": "5.1.0",
-    "@yunsoft/yuncms-core": "0.1.10",
+    "@yunsoft/yuncms-core": "0.1.12",
     "express": "5.2.1",
     "ldapts": "9.0.0",
     "openid-client": "6.8.7",

package/src/error-response.js

@@ -5,6 +5,7 @@ const STATUS_BY_CODE = new Map([
   ['UNAUTHORIZED', 401],
   ['FORBIDDEN', 403],
   ['FORBIDDEN_FIELD', 403],
+  ['EMAIL_NOT_VERIFIED', 403],
   ['SELF_ADMIN_MUTATION_FORBIDDEN', 403],
   ['PROTECTED_ROLE', 403],
   ['SYSTEM_SCHEMA_READ_ONLY', 403],
@@ -49,6 +50,7 @@ const STATUS_BY_CODE = new Map([
   ['INVALID_MAIL_MESSAGE', 400],
   ['INVALID_AI_REQUEST', 400],
   ['INVALID_AI_CONFIG', 400],
+  ['INVALID_MCP_CONFIG', 400],
   ['AI_TOOL_ARGUMENTS_INVALID', 400],
   ['STORAGE_NOT_FOUND', 400],
   ['STORAGE_INVENTORY_UNSUPPORTED', 400],

package/src/mcp/config.js

@@ -0,0 +1,154 @@
+export const DEFAULT_MCP_SETTINGS = Object.freeze({
+  enabled: false,
+  writesEnabled: false,
+  requireAuthentication: true,
+  allowedOrigins: Object.freeze([]),
+  allowedHosts: Object.freeze([]),
+  maxItems: 100,
+  maxResultBytes: 1_000_000,
+});
+
+const PATCH_KEYS = new Set([
+  'enabled',
+  'writes_enabled',
+  'require_authentication',
+  'allowed_origins',
+  'allowed_hosts',
+  'max_items',
+  'max_result_bytes',
+]);
+
+function configError(message) {
+  const error = new Error(message);
+  error.code = 'INVALID_MCP_CONFIG';
+  return error;
+}
+
+function normalizeBoolean(value, name) {
+  if (typeof value !== 'boolean') throw configError(`${name} must be a boolean`);
+  return value;
+}
+
+function normalizeInteger(value, name, { min, max }) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw configError(`${name} must be an integer between ${min} and ${max}`);
+  }
+  return parsed;
+}
+
+function listValues(value, name) {
+  let source = value;
+  if (typeof source === 'string') {
+    const trimmed = source.trim();
+    if (trimmed.startsWith('[')) {
+      try {
+        source = JSON.parse(trimmed);
+      } catch {
+        throw configError(`${name} must be a list`);
+      }
+    } else {
+      source = source.split(/[\n,]/);
+    }
+  }
+  if (!Array.isArray(source)) throw configError(`${name} must be a list`);
+  const entries = source.map((entry) => {
+    if (typeof entry !== 'string') throw configError(`${name} entries must be strings`);
+    return entry.trim();
+  }).filter(Boolean);
+  if (entries.length > 50) throw configError(`${name} cannot contain more than 50 entries`);
+  return entries;
+}
+
+export function normalizeMcpOrigins(value) {
+  return [...new Set(listValues(value, 'allowed_origins').map((entry) => {
+    let url;
+    try {
+      url = new URL(entry);
+    } catch {
+      throw configError(`allowed_origins contains an invalid URL: ${entry}`);
+    }
+    if (!['http:', 'https:'].includes(url.protocol)) {
+      throw configError(`allowed_origins must use http or https: ${entry}`);
+    }
+    if (url.username || url.password) {
+      throw configError(`allowed_origins cannot include credentials: ${entry}`);
+    }
+    return url.origin.toLowerCase();
+  }))];
+}
+
+export function normalizeMcpHosts(value) {
+  return [...new Set(listValues(value, 'allowed_hosts').map((entry) => {
+    if (/[:][/][/]|[\\/?#@\s\0]/.test(entry)) {
+      throw configError(`allowed_hosts contains an invalid host: ${entry}`);
+    }
+    let url;
+    try {
+      url = new URL(`http://${entry}`);
+    } catch {
+      throw configError(`allowed_hosts contains an invalid host: ${entry}`);
+    }
+    if (url.username || url.password || url.pathname !== '/' || url.search || url.hash || !url.host) {
+      throw configError(`allowed_hosts contains an invalid host: ${entry}`);
+    }
+    return url.host.toLowerCase();
+  }))];
+}
+
+export function normalizeMcpSettingsPatch(patch = {}) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+    throw configError('MCP settings patch must be an object');
+  }
+  const keys = Object.keys(patch);
+  if (keys.length === 0 || keys.some((key) => !PATCH_KEYS.has(key))) {
+    throw configError('MCP settings patch contains unsupported properties');
+  }
+  const normalized = {};
+  if (Object.hasOwn(patch, 'enabled')) normalized.enabled = normalizeBoolean(patch.enabled, 'enabled');
+  if (Object.hasOwn(patch, 'writes_enabled')) normalized.writesEnabled = normalizeBoolean(patch.writes_enabled, 'writes_enabled');
+  if (Object.hasOwn(patch, 'require_authentication')) normalized.requireAuthentication = normalizeBoolean(patch.require_authentication, 'require_authentication');
+  if (Object.hasOwn(patch, 'allowed_origins')) normalized.allowedOrigins = normalizeMcpOrigins(patch.allowed_origins);
+  if (Object.hasOwn(patch, 'allowed_hosts')) normalized.allowedHosts = normalizeMcpHosts(patch.allowed_hosts);
+  if (Object.hasOwn(patch, 'max_items')) normalized.maxItems = normalizeInteger(patch.max_items, 'max_items', { min: 1, max: 500 });
+  if (Object.hasOwn(patch, 'max_result_bytes')) normalized.maxResultBytes = normalizeInteger(patch.max_result_bytes, 'max_result_bytes', { min: 10_000, max: 10_000_000 });
+  return normalized;
+}
+
+function rowList(value, name, normalize) {
+  try {
+    return normalize(value);
+  } catch (error) {
+    if (error?.code === 'INVALID_MCP_CONFIG') throw error;
+    throw configError(`${name} contains invalid saved data`);
+  }
+}
+
+export function mcpRuntimeSettingsFromRow(row) {
+  if (!row) throw configError('MCP settings are missing; run YunCMS bootstrap');
+  return Object.freeze({
+    enabled: Boolean(row.enabled),
+    writesEnabled: Boolean(row.writes_enabled),
+    requireAuthentication: Boolean(row.require_authentication),
+    allowedOrigins: Object.freeze(rowList(row.allowed_origins, 'allowed_origins', normalizeMcpOrigins)),
+    allowedHosts: Object.freeze(rowList(row.allowed_hosts, 'allowed_hosts', normalizeMcpHosts)),
+    maxItems: normalizeInteger(row.max_items, 'max_items', { min: 1, max: 500 }),
+    maxResultBytes: normalizeInteger(row.max_result_bytes, 'max_result_bytes', { min: 10_000, max: 10_000_000 }),
+  });
+}
+
+export function mcpAdminSettingsFromRow(row) {
+  const runtime = mcpRuntimeSettingsFromRow(row);
+  return {
+    enabled: runtime.enabled,
+    writes_enabled: runtime.writesEnabled,
+    require_authentication: runtime.requireAuthentication,
+    allowed_origins: [...runtime.allowedOrigins],
+    allowed_hosts: [...runtime.allowedHosts],
+    max_items: runtime.maxItems,
+    max_result_bytes: runtime.maxResultBytes,
+    updated_at: row.updated_at ?? null,
+  };
+}
+
+export { configError };

package/src/mcp/settings-store.js

@@ -0,0 +1,78 @@
+import {
+  mcpAdminSettingsFromRow,
+  mcpRuntimeSettingsFromRow,
+  normalizeMcpSettingsPatch,
+} from './config.js';
+
+function settingsError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function columnAssignments(normalized) {
+  const assignments = [];
+  const params = [];
+  const add = (column, value) => {
+    assignments.push(`${column} = ?`);
+    params.push(value);
+  };
+  if (Object.hasOwn(normalized, 'enabled')) add('enabled', normalized.enabled ? 1 : 0);
+  if (Object.hasOwn(normalized, 'writesEnabled')) add('writes_enabled', normalized.writesEnabled ? 1 : 0);
+  if (Object.hasOwn(normalized, 'requireAuthentication')) add('require_authentication', normalized.requireAuthentication ? 1 : 0);
+  if (Object.hasOwn(normalized, 'allowedOrigins')) add('allowed_origins', JSON.stringify(normalized.allowedOrigins));
+  if (Object.hasOwn(normalized, 'allowedHosts')) add('allowed_hosts', JSON.stringify(normalized.allowedHosts));
+  if (Object.hasOwn(normalized, 'maxItems')) add('max_items', normalized.maxItems);
+  if (Object.hasOwn(normalized, 'maxResultBytes')) add('max_result_bytes', normalized.maxResultBytes);
+  return { assignments, params };
+}
+
+export class McpSettingsStore {
+  constructor({ database } = {}) {
+    if (!database) throw new Error('MCP settings store requires database');
+    this.database = database;
+  }
+
+  async #row() {
+    const [rows] = await this.database.query(
+      `SELECT id, enabled, writes_enabled, require_authentication, allowed_origins,
+              allowed_hosts, max_items, max_result_bytes, updated_at
+       FROM yuncms_mcp_settings
+       WHERE id = 1
+       LIMIT 1`,
+    );
+    const row = rows[0];
+    if (!row) throw settingsError('DATABASE_MIGRATION_REQUIRED', 'MCP settings are missing; run YunCMS bootstrap');
+    return row;
+  }
+
+  async readAdmin() {
+    return mcpAdminSettingsFromRow(await this.#row());
+  }
+
+  async readRuntime() {
+    return mcpRuntimeSettingsFromRow(await this.#row());
+  }
+
+  async update(patch = {}) {
+    const normalized = normalizeMcpSettingsPatch(patch);
+    const current = await this.#row();
+    const { assignments, params } = columnAssignments(normalized);
+    if (assignments.length === 0) throw settingsError('INVALID_MCP_CONFIG', 'MCP settings patch has no effective changes');
+
+    const effectiveEnabled = Object.hasOwn(normalized, 'enabled') ? normalized.enabled : Boolean(current.enabled);
+    const effectiveAllowedHosts = Object.hasOwn(normalized, 'allowedHosts')
+      ? normalized.allowedHosts
+      : mcpRuntimeSettingsFromRow(current).allowedHosts;
+    if (effectiveEnabled && effectiveAllowedHosts.length === 0) {
+      throw settingsError('INVALID_MCP_CONFIG', 'Add at least one allowed host before enabling MCP');
+    }
+
+    params.push(1);
+    await this.database.query(
+      `UPDATE yuncms_mcp_settings SET ${assignments.join(', ')} WHERE id = ?`,
+      params,
+    );
+    return this.readAdmin();
+  }
+}

package/src/mcp.js

@@ -327,10 +327,55 @@ export function createMcpAccessGuard(mcpConfig = {}) {
   };
 }
 
-export function createMcpRouter({ config, logger = console } = {}) {
-  if (!config?.mcp?.enabled) return null;
+export function requireMcpAdministrator(req) {
+  if (req?.authMethod === 'public' || !req?.accountability?.user) {
+    const error = new Error('MCP settings require an authenticated YunCMS account');
+    error.code = 'UNAUTHORIZED';
+    throw error;
+  }
+  if (req.accountability?.admin === true || req.accountability?.system === true) return;
+  const error = new Error('MCP settings require administrator access');
+  error.code = 'FORBIDDEN';
+  throw error;
+}
+
+export function createMcpRouter({ settingsStore, logger = console } = {}) {
+  if (!settingsStore) throw new Error('MCP settings store is required');
   const router = express.Router();
-  router.use(createMcpAccessGuard(config.mcp));
+
+  router.get('/settings', async (req, res, next) => {
+    try {
+      requireMcpAdministrator(req);
+      return res.json({ data: await settingsStore.readAdmin(), request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.patch('/settings', async (req, res, next) => {
+    try {
+      requireMcpAdministrator(req);
+      return res.json({ data: await settingsStore.update(req.body ?? {}), request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.use(async (req, res, next) => {
+    try {
+      const mcpConfig = await settingsStore.readRuntime();
+      if (!mcpConfig.enabled) {
+        return res.status(404).json({
+          errors: [{ code: 'MCP_DISABLED', message: 'MCP is disabled', request_id: req.id ?? null }],
+        });
+      }
+      req.mcpConfig = mcpConfig;
+      return createMcpAccessGuard(mcpConfig)(req, res, next);
+    } catch (error) {
+      return next(error);
+    }
+  });
+
   router.all('/', (req, res, next) => {
     if (req.method === 'POST') return next();
     res.set('allow', 'POST');
@@ -344,7 +389,7 @@ export function createMcpRouter({ config, logger = console } = {}) {
       code: error?.code ?? null,
     });
     const handler = createMcpHandler(
-      () => createRequestMcpServer(req, config.mcp),
+      () => createRequestMcpServer(req, req.mcpConfig),
       { legacy: 'stateless', onerror: reportError },
     );
     const nodeHandler = toNodeHandler(handler, { onerror: reportError });

package/src/routes/auth.js

@@ -1,3 +1,4 @@
+import { createSystemAccountability } from '@yunsoft/yuncms-core';
 import express from 'express';
 
 import { createFixedWindowRateLimit } from '../rate-limit.js';
@@ -7,10 +8,20 @@ function service(req, name) {
   const Service = req.context.services[name];
   return new Service(serviceOptionsFromRequest(req));
 }
+function systemService(req, name) {
+  const Service = req.context.services[name];
+  return new Service({
+    ...serviceOptionsFromRequest(req),
+    accountability: createSystemAccountability(),
+  });
+}
 function authService(req) { return service(req, 'AuthService'); }
 function authTokensService(req) { return service(req, 'AuthTokensService'); }
+function systemAuthTokensService(req) { return systemService(req, 'AuthTokensService'); }
 function apiTokensService(req) { return service(req, 'ApiTokensService'); }
 function usersService(req) { return service(req, 'UsersService'); }
+function systemUsersService(req) { return systemService(req, 'UsersService'); }
+function studioSettingsService(req) { return service(req, 'StudioSettingsService'); }
 function externalAuthService(req, registry) {
   const Service = req.context.services.ExternalAuthService;
   return new Service({
@@ -45,6 +56,14 @@ function actionUrl(config, action, token) {
   return `${config.auth.publicUrl}/?auth_action=${encodeURIComponent(action)}&token=${encodeURIComponent(token)}`;
 }
 
+function verificationMessage(config, token) {
+  const url = actionUrl(config, 'verify', token);
+  return {
+    subject: 'Verify your YunCMS email',
+    text: `Verify your YunCMS email address by opening this link:\n${url}\n\nIf you did not request this, you can ignore this message.`,
+  };
+}
+
 function noStore(req, res, next) {
   res.set('cache-control', 'no-store');
   res.set('pragma', 'no-cache');
@@ -97,6 +116,43 @@ export function createAuthRouter({
     res.json({ data: externalAuthRegistry?.publicProviders?.() ?? [] });
   });
 
+  router.post('/register', actionLimit, async (req, res) => {
+    const settings = await studioSettingsService(req).readPublic();
+    const verificationRequired = settings.public_registration_require_email_verification === true;
+    const transport = verificationRequired ? requireMailer(mailer) : null;
+    const data = await usersService(req).registerPublic(req.body ?? {});
+
+    if (verificationRequired) {
+      try {
+        const result = await systemAuthTokensService(req).createEmailVerification(data.id);
+        const message = verificationMessage(config, result.token);
+        await transport.send({ to: data.email, ...message }, {
+          accountability: req.accountability,
+          requestId: req.id,
+        });
+      } catch (error) {
+        try {
+          await systemUsersService(req).deleteOne(data.id);
+        } catch (cleanupError) {
+          logger.error?.('YunCMS public registration cleanup failed', {
+            requestId: req.id,
+            user: data.id,
+            code: cleanupError?.code,
+            message: cleanupError?.message,
+          });
+        }
+        throw error;
+      }
+    }
+
+    res.status(201).json({
+      data: {
+        ...data,
+        email_verification_required: verificationRequired,
+      },
+    });
+  });
+
   router.post('/login', loginLimit, async (req, res) => {
     const result = await authService(req).login({ email: req.body?.email, password: req.body?.password, ip: req.ip ?? null, userAgent: req.get('user-agent') ?? null });
     res.json({ data: result });
@@ -210,12 +266,35 @@ export function createAuthRouter({
     res.status(204).end();
   });
   router.post('/email-verification/request', actionLimit, async (req, res) => {
-    const transport = requireMailer(mailer);
     if (!req.accountability?.user) {
-      const error = new Error('Authentication is required to request email verification');
-      error.code = 'UNAUTHORIZED';
-      throw error;
+      const settings = await studioSettingsService(req).readPublic();
+      if (settings.public_registration_require_email_verification !== true) {
+        res.status(202).json({ data: { accepted: true } });
+        return;
+      }
+
+      const transport = requireMailer(mailer);
+      const result = await systemAuthTokensService(req).requestEmailVerification(req.body?.email);
+      if (result) {
+        try {
+          const message = verificationMessage(config, result.token);
+          await transport.send({ to: result.user.email, ...message }, {
+            accountability: req.accountability,
+            requestId: req.id,
+          });
+        } catch (error) {
+          logger.error?.('YunCMS public email verification mail delivery failed', {
+            requestId: req.id,
+            code: error?.code,
+            message: error?.message,
+          });
+        }
+      }
+      res.status(202).json({ data: { accepted: true } });
+      return;
     }
+
+    const transport = requireMailer(mailer);
     const userId = req.body?.user ?? req.accountability.user;
     const user = await usersService(req).readOne(userId);
     if (!user) {
@@ -224,8 +303,11 @@ export function createAuthRouter({
       throw error;
     }
     const result = await authTokensService(req).createEmailVerification(userId);
-    const url = actionUrl(config, 'verify', result.token);
-    await transport.send({ to: user.email, subject: 'Verify your YunCMS email', text: `Verify your YunCMS email address by opening this link:\n${url}\n\nIf you did not request this, you can ignore this message.` }, { accountability: req.accountability, requestId: req.id });
+    const message = verificationMessage(config, result.token);
+    await transport.send({ to: user.email, ...message }, {
+      accountability: req.accountability,
+      requestId: req.id,
+    });
     res.status(202).json({ data: { accepted: true } });
   });
   router.post('/email-verification/confirm', actionLimit, async (req, res) => {

package/src/routes/studio-settings.js

@@ -26,6 +26,10 @@ export function createStudioSettingsRouter() {
     sendImageAsset(res, await settingsService(req).readFaviconContent());
   });
 
+  router.get('/admin', async (req, res) => {
+    res.json({ data: await settingsService(req).readOne() });
+  });
+
   router.get('/', async (req, res) => {
     res.json({ data: await settingsService(req).readPublic() });
   });

package/src/server.js

@@ -28,6 +28,7 @@ import { loadExternalAuthConfig } from './external-auth/config.js';
 import { ExternalAuthProviderRegistry } from './external-auth/providers.js';
 import { loadExtensionRuntime } from './extensions/runtime.js';
 import { createMcpRouter } from './mcp.js';
+import { McpSettingsStore } from './mcp/settings-store.js';
 import { createAiRouter } from './routes/ai.js';
 
 loadEnvFileIfPresent();
@@ -134,7 +135,8 @@ async function start() {
   });
   const aiAssistant = new AiAssistantService({ settingsStore: aiSettingsStore, logger });
   const aiRouter = createAiRouter({ assistant: aiAssistant, settingsStore: aiSettingsStore });
-  const mcpRouter = createMcpRouter({ config, logger });
+  const mcpSettingsStore = new McpSettingsStore({ database: pool });
+  const mcpRouter = createMcpRouter({ settingsStore: mcpSettingsStore, logger });
   mailer?.setEmitter(emitter);
   registerInternalAudit({ emitter, services });
 
@@ -219,4 +221,4 @@ start().catch(async (error) => {
   await redisClient?.close().catch(() => {});
   await closeDatabasePool(pool).catch(() => {});
   process.exit(1);
-});
+});