@yunsoft/yuncms-api 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunsoft/yuncms-api",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Express API runtime and bundled Studio server for YunCMS.",
   "license": "MIT",
   "type": "module",
@@ -32,7 +32,13 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@yunsoft/yuncms-core": "0.1.5",
-    "express": "5.2.1"
+    "@modelcontextprotocol/node": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
+    "@node-saml/node-saml": "5.1.0",
+    "@yunsoft/yuncms-core": "0.1.7",
+    "express": "5.2.1",
+    "ldapts": "9.0.0",
+    "openid-client": "6.8.7",
+    "zod": "4.4.3"
   }
 }

package/src/app.js

@@ -23,19 +23,10 @@ import { createStudioMiddleware } from './studio.js';
 
 const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
 const CONTENT_SECURITY_POLICY = [
-  "default-src 'self'",
-  "base-uri 'self'",
-  "object-src 'none'",
-  "frame-ancestors 'none'",
-  "script-src 'self'",
-  "style-src 'self' 'unsafe-inline'",
-  "img-src 'self' data: blob: https://yunsoft.com",
-  "font-src 'self' data:",
-  "connect-src 'self'",
-  "media-src 'self' blob:",
-  "frame-src 'self' blob:",
-  "worker-src 'self' blob:",
-  "form-action 'self'",
+  "default-src 'self'", "base-uri 'self'", "object-src 'none'", "frame-ancestors 'none'",
+  "script-src 'self'", "style-src 'self' 'unsafe-inline'", "img-src 'self' data: blob: https://yunsoft.com",
+  "font-src 'self' data:", "connect-src 'self'", "media-src 'self' blob:", "frame-src 'self' blob:",
+  "worker-src 'self' blob:", "form-action 'self'",
 ].join('; ');
 
 function securityHeaders(req, res, next) {
@@ -47,9 +38,7 @@ function securityHeaders(req, res, next) {
   res.set('cross-origin-opener-policy', 'same-origin');
   res.set('x-dns-prefetch-control', 'off');
   res.set('content-security-policy', CONTENT_SECURITY_POLICY);
-  if (req.secure === true) {
-    res.set('strict-transport-security', 'max-age=15552000; includeSubDomains');
-  }
+  if (req.secure === true) res.set('strict-transport-security', 'max-age=15552000; includeSubDomains');
   next();
 }
 
@@ -57,14 +46,12 @@ function studioCors(config) {
   return (req, res, next) => {
     const origin = req.get('origin');
     const allowedOrigin = config?.server?.studioOrigin;
-
     if (origin && allowedOrigin && origin === allowedOrigin) {
       res.set('access-control-allow-origin', origin);
       res.set('vary', 'Origin');
-      res.set('access-control-allow-headers', 'content-type, authorization, x-request-id, x-filename, x-title, x-mimetype');
+      res.set('access-control-allow-headers', 'content-type, authorization, x-request-id, x-filename, x-title, x-mimetype, mcp-protocol-version, mcp-method, mcp-name');
       res.set('access-control-allow-methods', 'GET,POST,PATCH,DELETE,OPTIONS');
     }
-
     if (req.method === 'OPTIONS') return res.sendStatus(204);
     return next();
   };
@@ -77,16 +64,55 @@ function requestIdentity(req, res, next) {
   next();
 }
 
-function createApiRateLimit(config) {
+function createApiRateLimit(config, rateLimitStore = null, logger = console) {
   const limits = config?.server?.rateLimit;
   if (!limits?.enabled) return null;
   return createFixedWindowRateLimit({
     windowMs: limits.windowMs,
     max: limits.max,
     maxBuckets: limits.maxBuckets,
+    store: limits.store === 'redis' ? rateLimitStore : null,
+    scope: 'api',
+    failureMode: limits.failureMode ?? 'best-effort',
+    logger,
   });
 }
 
+function requestEventMetadata(req, res, startedAt) {
+  return {
+    requestId: req.id ?? null,
+    method: req.method,
+    route: req.route?.path ?? req.path,
+    status: res.statusCode,
+    durationMs: Math.max(0, Date.now() - startedAt),
+    accountability: req.accountability ? {
+      user: req.accountability.user ?? null,
+      role: req.accountability.role ?? null,
+      admin: req.accountability.admin === true,
+      system: req.accountability.system === true,
+    } : null,
+    ip: req.ip ?? null,
+  };
+}
+
+function createRequestEvents(emitter) {
+  if (!emitter) return null;
+  return (req, res, next) => {
+    const startedAt = Date.now();
+    emitter.action('request.received', requestEventMetadata(req, res, startedAt), {
+      accountability: req.accountability,
+      requestId: req.id,
+    }).catch(() => {});
+    res.once('finish', () => {
+      emitter.action('request.completed', requestEventMetadata(req, res, startedAt), {
+        accountability: req.accountability,
+        requestId: req.id,
+      }).catch(() => {});
+    });
+    next();
+  };
+}
+
 export function createApp({
   pool,
   config,
@@ -97,7 +123,11 @@ export function createApp({
   emitter = null,
   storage = null,
   mailer = null,
+  rateLimitStore = null,
+  redisClient = null,
+  externalAuthRegistry = null,
   endpointExtensions = [],
+  mcpRouter = null,
   studioRoot = undefined,
 }) {
   if (!pool) throw new Error('Database pool is required');
@@ -118,40 +148,48 @@ export function createApp({
   });
 
   app.get('/ready', async (req, res) => {
+    const failures = [];
     try {
       const ready = await pingDatabase(pool);
-      if (!ready) throw new Error('Database ping returned an unexpected result');
-      res.json({ status: 'ready', request_id: req.id });
-    } catch (error) {
-      logger.warn?.('YunCMS readiness check failed', { requestId: req.id, error });
-      res.status(503).json({
-        status: 'not_ready',
-        request_id: req.id,
-        errors: [{ code: 'DATABASE_UNAVAILABLE', message: 'Database is not ready' }],
-      });
+      if (!ready) failures.push({ code: 'DATABASE_UNAVAILABLE', message: 'Database is not ready' });
+    } catch {
+      failures.push({ code: 'DATABASE_UNAVAILABLE', message: 'Database is not ready' });
     }
+    if (config.redis?.required && redisClient) {
+      try {
+        if (!await redisClient.ping()) throw new Error('Unexpected Redis ping result');
+      } catch {
+        failures.push({ code: 'SHARED_STATE_UNAVAILABLE', message: 'Required shared state is not ready' });
+      }
+    }
+    if (failures.length) {
+      logger.warn?.('YunCMS readiness check failed', { requestId: req.id, failures: failures.map((entry) => entry.code) });
+      return res.status(503).json({ status: 'not_ready', request_id: req.id, errors: failures });
+    }
+    return res.json({
+      status: 'ready',
+      request_id: req.id,
+      shared_state: {
+        cache: config.cache?.store ?? 'memory',
+        api_rate_limit: config.server?.rateLimit?.store ?? 'memory',
+        auth_rate_limit: config.auth?.rateLimit?.store ?? 'memory',
+      },
+    });
   });
 
   app.use(createStudioMiddleware({ root: studioRoot }));
-
   const pressureLimit = createPressureLimit(config.server?.pressure);
   if (pressureLimit) app.use(pressureLimit);
-
-  const apiRateLimit = createApiRateLimit(config);
+  const apiRateLimit = createApiRateLimit(config, rateLimitStore, logger);
   if (apiRateLimit) app.use(apiRateLimit);
 
-  app.use(createAuthenticationMiddleware({
-    pool,
-    config,
-    logger,
-    services,
-    schemaCache,
-    permissionCache,
-    emitter,
-    storage,
-  }));
+  app.use(createAuthenticationMiddleware({ pool, config, logger, services, schemaCache, permissionCache, emitter, storage }));
+  const requestEvents = createRequestEvents(emitter);
+  if (requestEvents) app.use(requestEvents);
+
+  if (mcpRouter) app.use('/mcp', mcpRouter);
   app.use('/studio-settings', createStudioSettingsRouter());
-  app.use('/auth', createAuthRouter({ mailer, config, logger }));
+  app.use('/auth', createAuthRouter({ mailer, config, logger, rateLimitStore, externalAuthRegistry }));
   app.use('/items', createItemsRouter());
   app.use('/schema', createSystemSchemaRouter({ schemaCache }));
   app.use('/schema', createSchemaRouter({ schemaCache }));
@@ -162,18 +200,22 @@ export function createApp({
   app.use('/audit', createAuditRouter());
 
   for (const extension of endpointExtensions) {
-    if (!extension?.id || !extension?.router) {
-      throw new Error('Invalid endpoint extension runtime entry');
-    }
+    if (!extension?.id || !extension?.router) throw new Error('Invalid endpoint extension runtime entry');
     app.use(`/extensions/${encodeURIComponent(extension.id)}`, extension.router);
   }
 
   app.use((req, res) => {
-    res.status(404).json({
-      errors: [{ code: 'NOT_FOUND', message: 'Route not found', request_id: req.id }],
-    });
+    res.status(404).json({ errors: [{ code: 'NOT_FOUND', message: 'Route not found', request_id: req.id }] });
+  });
+  app.use((error, req, res, next) => {
+    if (emitter) {
+      emitter.action('request.failed', {
+        ...requestEventMetadata(req, res, Date.now()),
+        error: { code: error?.code ?? 'INTERNAL_ERROR' },
+      }, { accountability: req.accountability, requestId: req.id }).catch(() => {});
+    }
+    next(error);
   });
-
   app.use(apiErrorHandler(logger));
   return app;
 }
@@ -181,6 +223,7 @@ export function createApp({
 export {
   CONTENT_SECURITY_POLICY,
   createApiRateLimit,
+  createRequestEvents,
   requestIdentity,
   securityHeaders,
   studioCors,

package/src/error-response.js

@@ -41,6 +41,7 @@ const STATUS_BY_CODE = new Map([
   ['INVALID_ON_DELETE', 400],
   ['INVALID_STORAGE_KEY', 400],
   ['INVALID_FILE_CONTENT', 400],
+  ['FILE_MIME_MISMATCH', 400],
   ['INVALID_MAIL_MESSAGE', 400],
   ['STORAGE_NOT_FOUND', 400],
   ['STORAGE_INVENTORY_UNSUPPORTED', 400],

package/src/extensions/runtime.js

@@ -2,6 +2,7 @@ import { pathToFileURL } from 'node:url';
 import express from 'express';
 
 import { discoverExtensions } from './discovery.js';
+import { ExtensionScheduler } from './scheduler.js';
 
 function extensionError(code, message) {
   const error = new Error(message);
@@ -54,19 +55,39 @@ function createBaseContext({ services, database, schemaCache, emitter, storage,
   });
 }
 
-function hookRegistrationApi(emitter, baseContext) {
+function hookRegistrationApi(emitter, baseContext, manifest, scheduler) {
+  const registration = Object.freeze({
+    extensionId: manifest.id,
+    priority: Number.isInteger(manifest.priority) ? manifest.priority : 0,
+  });
+
   return Object.freeze({
-    filter(event, handler) {
+    filter(event, handler, options = {}) {
       return emitter.registerFilter(event, (payload, eventContext) =>
-        handler(payload, { ...baseContext, ...eventContext }));
+        handler(payload, { ...baseContext, ...eventContext }), {
+        ...registration,
+        ...options,
+        extensionId: manifest.id,
+      });
     },
-    action(event, handler) {
+    action(event, handler, options = {}) {
       return emitter.registerAction(event, (payload, eventContext) =>
-        handler(payload, { ...baseContext, ...eventContext }));
+        handler(payload, { ...baseContext, ...eventContext }), {
+        ...registration,
+        ...options,
+        extensionId: manifest.id,
+      });
     },
-    init(event, handler) {
+    init(event, handler, options = {}) {
       return emitter.registerInit(event, (eventContext) =>
-        handler({ ...baseContext, ...eventContext }));
+        handler({ ...baseContext, ...eventContext }), {
+        ...registration,
+        ...options,
+        extensionId: manifest.id,
+      });
+    },
+    schedule(expression, handler, options = {}) {
+      return scheduler.register(manifest.id, expression, handler, options);
     },
   });
 }
@@ -89,14 +110,22 @@ export async function loadExtensionRuntime({
 
   const manifests = await discoverExtensions({ rootDir, localDirectory, includeDependencies });
   const baseContext = createBaseContext({ services, database, schemaCache, emitter, storage, logger, env });
+  const scheduler = new ExtensionScheduler({
+    database,
+    services,
+    schemaCache,
+    emitter,
+    storage,
+    logger,
+    env,
+  });
   const endpointExtensions = [];
-  const hookApi = hookRegistrationApi(emitter, baseContext);
 
   for (const manifest of manifests) {
     const definition = await importExtension(manifest);
 
     if (manifest.type === 'hook') {
-      await definition.register(hookApi, baseContext);
+      await definition.register(hookRegistrationApi(emitter, baseContext, manifest, scheduler), baseContext);
       logger.info?.(`Loaded YunCMS hook extension: ${manifest.id}`);
       continue;
     }
@@ -117,5 +146,11 @@ export async function loadExtensionRuntime({
     async init(event) {
       await emitter.init(event, baseContext);
     },
+    startSchedules() {
+      scheduler.start();
+    },
+    async stopSchedules(options = {}) {
+      return scheduler.stop(options);
+    },
   });
 }

package/src/extensions/scheduler.js

@@ -0,0 +1,288 @@
+import { createHash } from 'node:crypto';
+import {
+  createSystemAccountability,
+  withAdvisoryLock,
+} from '@yunsoft/yuncms-core';
+
+const CRON_FIELD_RULES = Object.freeze([
+  { name: 'minute', min: 0, max: 59 },
+  { name: 'hour', min: 0, max: 23 },
+  { name: 'day', min: 1, max: 31 },
+  { name: 'month', min: 1, max: 12 },
+  { name: 'weekday', min: 0, max: 6 },
+]);
+const JOB_ID_PATTERN = /^[A-Za-z0-9._:-]{1,100}$/;
+
+function scheduleError(message) {
+  const error = new Error(message);
+  error.code = 'INVALID_EXTENSION_SCHEDULE';
+  return error;
+}
+
+function integerToken(value, rule, label) {
+  if (!/^\d+$/.test(value)) throw scheduleError(`Invalid ${label} cron token: ${value}`);
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < rule.min || number > rule.max) {
+    throw scheduleError(`${label} must be between ${rule.min} and ${rule.max}`);
+  }
+  return number;
+}
+
+function rangeValues(start, end, step, rule, label) {
+  if (start > end) throw scheduleError(`Invalid ${label} cron range: ${start}-${end}`);
+  const values = [];
+  for (let value = start; value <= end; value += step) values.push(value);
+  return values;
+}
+
+function parseCronPart(part, rule) {
+  const [base, rawStep, extra] = part.split('/');
+  if (extra !== undefined) throw scheduleError(`Invalid ${rule.name} cron token: ${part}`);
+  const step = rawStep === undefined ? 1 : integerToken(rawStep, { min: 1, max: rule.max - rule.min + 1 }, `${rule.name} step`);
+
+  if (base === '*') return rangeValues(rule.min, rule.max, step, rule, rule.name);
+  if (base.includes('-')) {
+    const bits = base.split('-');
+    if (bits.length !== 2) throw scheduleError(`Invalid ${rule.name} cron range: ${base}`);
+    return rangeValues(
+      integerToken(bits[0], rule, rule.name),
+      integerToken(bits[1], rule, rule.name),
+      step,
+      rule,
+      rule.name,
+    );
+  }
+  if (rawStep !== undefined) throw scheduleError(`Cron step requires * or range for ${rule.name}`);
+  return [integerToken(base, rule, rule.name)];
+}
+
+function parseCronField(value, rule) {
+  if (!value) throw scheduleError(`Cron ${rule.name} field is required`);
+  const values = new Set();
+  for (const part of value.split(',')) {
+    if (!part) throw scheduleError(`Invalid ${rule.name} cron list`);
+    for (const number of parseCronPart(part, rule)) values.add(number);
+  }
+  return values;
+}
+
+export function parseCronExpression(expression) {
+  if (typeof expression !== 'string') throw scheduleError('Cron expression must be a string');
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) throw scheduleError('Cron expression must contain exactly 5 fields');
+  return Object.freeze(CRON_FIELD_RULES.map((rule, index) => parseCronField(fields[index], rule)));
+}
+
+export function cronMatches(parsed, date) {
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) throw new Error('Valid date is required');
+  const values = [
+    date.getMinutes(),
+    date.getHours(),
+    date.getDate(),
+    date.getMonth() + 1,
+    date.getDay(),
+  ];
+  return parsed.every((allowed, index) => allowed.has(values[index]));
+}
+
+function normalizeJobOptions(options = {}) {
+  const id = String(options.id ?? '').trim();
+  if (!JOB_ID_PATTERN.test(id)) {
+    throw scheduleError('Scheduled extension job requires a stable id using letters, numbers, dot, underscore, colon or dash');
+  }
+  const mode = options.mode ?? 'per_process';
+  if (!['per_process', 'singleton'].includes(mode)) {
+    throw scheduleError('Scheduled extension job mode must be per_process or singleton');
+  }
+  if ((options.overlap ?? 'skip') !== 'skip') {
+    throw scheduleError('Scheduled extension job overlap currently supports skip only');
+  }
+  if (options.accountability !== 'system') {
+    throw scheduleError("Scheduled extension jobs must explicitly set accountability: 'system'");
+  }
+  return Object.freeze({ id, mode, overlap: 'skip', accountability: 'system' });
+}
+
+function minuteKey(date) {
+  return `${date.getFullYear()}-${date.getMonth()}-${date.getDate()}-${date.getHours()}-${date.getMinutes()}`;
+}
+
+export function scheduleLockName(identity) {
+  const digest = createHash('sha256').update(String(identity)).digest('hex').slice(0, 40);
+  return `yuncms:schedule:${digest}`;
+}
+
+export class ExtensionScheduler {
+  constructor({
+    database,
+    services,
+    schemaCache,
+    emitter,
+    storage = null,
+    logger = console,
+    env,
+    now = () => new Date(),
+    lockRunner = withAdvisoryLock,
+  } = {}) {
+    if (!database || !services || !schemaCache || !emitter) {
+      throw new Error('Extension scheduler requires database, services, schemaCache and emitter');
+    }
+    this.database = database;
+    this.services = services;
+    this.schemaCache = schemaCache;
+    this.emitter = emitter;
+    this.storage = storage;
+    this.logger = logger;
+    this.env = env;
+    this.now = now;
+    this.lockRunner = lockRunner;
+    this.jobs = new Map();
+    this.timer = null;
+    this.stopping = false;
+    this.runningPromises = new Set();
+  }
+
+  register(extensionId, expression, handler, options = {}) {
+    if (typeof handler !== 'function') throw scheduleError('Scheduled extension handler must be a function');
+    const parsed = parseCronExpression(expression);
+    const normalized = normalizeJobOptions(options);
+    const identity = `${extensionId}:${normalized.id}`;
+    if (this.jobs.has(identity)) throw scheduleError(`Duplicate scheduled extension job: ${identity}`);
+    const job = {
+      identity,
+      extensionId,
+      expression,
+      parsed,
+      handler,
+      options: normalized,
+      running: false,
+      lastMinute: null,
+    };
+    this.jobs.set(identity, job);
+    return () => this.jobs.delete(identity);
+  }
+
+  async #context(job, date) {
+    const accountability = createSystemAccountability();
+    const schema = await this.schemaCache.get(this.database);
+    return Object.freeze({
+      services: this.services,
+      database: this.database,
+      logger: this.logger,
+      env: this.env,
+      emitter: this.emitter,
+      storage: this.storage,
+      accountability,
+      requestId: `schedule:${job.identity}:${date.toISOString()}`,
+      getSchema: () => this.schemaCache.get(this.database),
+      serviceOptions: async () => ({
+        accountability,
+        database: this.database,
+        schema,
+        logger: this.logger,
+        emitter: this.emitter,
+        storage: this.storage,
+        permissionCache: null,
+        requestId: `schedule:${job.identity}:${date.toISOString()}`,
+      }),
+      schedule: Object.freeze({
+        id: job.options.id,
+        extensionId: job.extensionId,
+        expression: job.expression,
+        mode: job.options.mode,
+        scheduledAt: date,
+      }),
+    });
+  }
+
+  async #execute(job, date) {
+    if (job.running) {
+      this.logger?.warn?.('Skipping overlapping YunCMS extension job', { job: job.identity });
+      return false;
+    }
+    job.running = true;
+    const startedAt = Date.now();
+    this.logger?.info?.('Starting YunCMS extension job', { job: job.identity, mode: job.options.mode });
+    try {
+      const run = async () => job.handler(await this.#context(job, date));
+      if (job.options.mode === 'singleton') {
+        try {
+          await this.lockRunner(
+            this.database,
+            scheduleLockName(job.identity),
+            run,
+            { timeoutSeconds: 0 },
+          );
+        } catch (error) {
+          if (error?.code === 'SCHEMA_LOCK_UNAVAILABLE') {
+            this.logger?.info?.('Skipping YunCMS singleton extension job owned by another replica', { job: job.identity });
+            return false;
+          }
+          throw error;
+        }
+      } else {
+        await run();
+      }
+      this.logger?.info?.('Completed YunCMS extension job', {
+        job: job.identity,
+        durationMs: Date.now() - startedAt,
+      });
+      return true;
+    } catch (error) {
+      this.logger?.error?.('YunCMS extension job failed', {
+        job: job.identity,
+        durationMs: Date.now() - startedAt,
+        code: error?.code ?? null,
+        message: error?.message ?? String(error),
+      });
+      return false;
+    } finally {
+      job.running = false;
+    }
+  }
+
+  async runDue(date = this.now()) {
+    if (this.stopping) return [];
+    const executions = [];
+    const key = minuteKey(date);
+    for (const job of this.jobs.values()) {
+      if (job.lastMinute === key || !cronMatches(job.parsed, date)) continue;
+      job.lastMinute = key;
+      const execution = this.#execute(job, date);
+      this.runningPromises.add(execution);
+      execution.finally(() => this.runningPromises.delete(execution));
+      executions.push(execution);
+    }
+    return Promise.all(executions);
+  }
+
+  start() {
+    if (this.timer || this.stopping) return;
+    const tick = () => this.runDue().catch((error) => {
+      this.logger?.error?.('YunCMS extension scheduler tick failed', { code: error?.code ?? null });
+    });
+    tick();
+    this.timer = setInterval(tick, 15_000);
+    this.timer.unref?.();
+  }
+
+  async stop({ timeoutMs = 5_000 } = {}) {
+    this.stopping = true;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    const running = [...this.runningPromises];
+    if (running.length === 0) return true;
+    let timeout;
+    const completed = await Promise.race([
+      Promise.allSettled(running).then(() => true),
+      new Promise((resolve) => {
+        timeout = setTimeout(() => resolve(false), timeoutMs);
+        timeout.unref?.();
+      }),
+    ]);
+    if (timeout) clearTimeout(timeout);
+    return completed;
+  }
+}
+
+export { normalizeJobOptions };