@yunsoft/yuncms-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yunsoft Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @yunsoft/yuncms-api
+
+Express API runtime and bundled React Studio server for YunCMS.
+
+The normal entry point is the `yuncms` executable provided by `@yunsoft/yuncms`. See the [project repository](https://github.com/Yunsoft-Software/yuncms) for configuration and deployment documentation.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@yunsoft/yuncms-api",
+  "version": "0.1.0",
+  "description": "Express API runtime and bundled Studio server for YunCMS.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "files": [
+    "src",
+    "studio-dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yunsoft-Software/yuncms.git",
+    "directory": "packages/api"
+  },
+  "homepage": "https://github.com/Yunsoft-Software/yuncms#readme",
+  "bugs": {
+    "url": "https://github.com/Yunsoft-Software/yuncms/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./server": "./src/server.js"
+  },
+  "scripts": {
+    "dev": "node --watch src/server.js",
+    "start": "node src/server.js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@yunsoft/yuncms-core": "0.1.0",
+    "express": "5.2.1"
+  }
+}

package/src/app.js

@@ -0,0 +1,130 @@
+import { randomUUID } from 'node:crypto';
+import express from 'express';
+import {
+  createCoreServiceRegistry,
+  pingDatabase,
+} from '@yunsoft/yuncms-core';
+
+import { createAuthenticationMiddleware } from './authentication.js';
+import { apiErrorHandler } from './error-response.js';
+import { createAuditRouter } from './routes/audit.js';
+import { createAuthRouter } from './routes/auth.js';
+import { createFilesRouter } from './routes/files.js';
+import { createItemsRouter } from './routes/items.js';
+import { createPermissionsRouter } from './routes/permissions.js';
+import { createRolesRouter } from './routes/roles.js';
+import { createSchemaRouter } from './routes/schema.js';
+import { createUsersRouter } from './routes/users.js';
+import { createStudioMiddleware } from './studio.js';
+
+function securityHeaders(req, res, next) {
+  res.set('x-content-type-options', 'nosniff');
+  res.set('x-frame-options', 'DENY');
+  res.set('referrer-policy', 'no-referrer');
+  res.set('permissions-policy', 'camera=(), microphone=(), geolocation=(), payment=(), usb=()');
+  res.set('cross-origin-resource-policy', 'same-origin');
+  next();
+}
+
+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-methods', 'GET,POST,PATCH,DELETE,OPTIONS');
+    }
+
+    if (req.method === 'OPTIONS') return res.sendStatus(204);
+    return next();
+  };
+}
+
+export function createApp({
+  pool,
+  config,
+  logger = console,
+  serviceRegistry = createCoreServiceRegistry(),
+  schemaCache = null,
+  emitter = null,
+  storage = null,
+  mailer = null,
+  endpointExtensions = [],
+  studioRoot = undefined,
+}) {
+  if (!pool) throw new Error('Database pool is required');
+  if (!config) throw new Error('Config is required');
+  if (!Array.isArray(endpointExtensions)) throw new Error('endpointExtensions must be an array');
+
+  const services = serviceRegistry.toObject();
+  const app = express();
+  app.disable('x-powered-by');
+  app.use(securityHeaders);
+  app.use(studioCors(config));
+  app.use(express.json({ limit: '1mb' }));
+  app.use((req, res, next) => {
+    req.id = req.get('x-request-id') || randomUUID();
+    res.set('x-request-id', req.id);
+    next();
+  });
+
+  app.get('/health', (req, res) => {
+    res.json({ status: 'ok', request_id: req.id });
+  });
+
+  app.get('/ready', async (req, res) => {
+    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' }],
+      });
+    }
+  });
+
+  app.use(createStudioMiddleware({ root: studioRoot }));
+
+  app.use(createAuthenticationMiddleware({
+    pool,
+    config,
+    logger,
+    services,
+    schemaCache,
+    emitter,
+    storage,
+  }));
+  app.use('/auth', createAuthRouter({ mailer, config, logger }));
+  app.use('/items', createItemsRouter());
+  app.use('/schema', createSchemaRouter());
+  app.use('/users', createUsersRouter());
+  app.use('/roles', createRolesRouter());
+  app.use('/permissions', createPermissionsRouter());
+  app.use('/files', createFilesRouter({ maxUploadBytes: config.storage?.maxUploadBytes }));
+  app.use('/audit', createAuditRouter());
+
+  for (const extension of endpointExtensions) {
+    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 }],
+    });
+  });
+
+  app.use(apiErrorHandler(logger));
+  return app;
+}
+
+export { securityHeaders, studioCors };

package/src/authentication.js

@@ -0,0 +1,91 @@
+import {
+  createAccountability,
+  createPublicAccountability,
+  createRequestContext,
+} from '@yunsoft/yuncms-core';
+
+function bearerToken(header) {
+  if (!header) return null;
+  const match = /^Bearer\s+([^\s]+)$/i.exec(header);
+  if (!match) {
+    const error = new Error('Authorization header must use Bearer authentication');
+    error.code = 'INVALID_CREDENTIALS';
+    throw error;
+  }
+  return match[1];
+}
+
+function isPublicAuthRoute(req) {
+  return req.method === 'POST' && (req.path === '/auth/login' || req.path === '/auth/refresh');
+}
+
+export function createAuthenticationMiddleware({
+  pool,
+  config,
+  logger,
+  services,
+  schemaCache = null,
+  emitter = null,
+  storage = null,
+}) {
+  return async (req, _res, next) => {
+    try {
+      const AuthService = services.AuthService;
+      const bootstrapAccountability = createPublicAccountability();
+      const auth = new AuthService({
+        accountability: bootstrapAccountability,
+        database: pool,
+        logger,
+        emitter,
+        storage,
+      });
+
+      const token = bearerToken(req.get('authorization'));
+      let accountability;
+
+      if (token) {
+        const identity = await auth.authenticateBearerToken(token);
+        accountability = createAccountability({
+          user: identity.user,
+          role: identity.role,
+          admin: identity.admin === true,
+        });
+        req.authToken = token;
+        req.authMethod = identity.authMethod;
+        req.sessionId = identity.session ?? null;
+        req.apiTokenId = identity.apiToken ?? null;
+      } else if (isPublicAuthRoute(req)) {
+        accountability = bootstrapAccountability;
+        req.authToken = null;
+        req.authMethod = 'public';
+        req.sessionId = null;
+        req.apiTokenId = null;
+      } else {
+        accountability = await auth.resolvePublicAccountability();
+        req.authToken = null;
+        req.authMethod = 'public';
+        req.sessionId = null;
+        req.apiTokenId = null;
+      }
+
+      const schema = schemaCache ? await schemaCache.get(pool) : null;
+      req.accountability = accountability;
+      req.context = createRequestContext({
+        accountability,
+        services,
+        database: pool,
+        schema,
+        logger,
+        env: config,
+        emitter,
+        storage,
+        requestId: req.id,
+      });
+      next();
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
+export { bearerToken, isPublicAuthRoute };

package/src/error-response.js

@@ -0,0 +1,143 @@
+import { normalizeDatabaseError } from '@yunsoft/yuncms-core';
+
+const STATUS_BY_CODE = new Map([
+  ['INVALID_CREDENTIALS', 401],
+  ['UNAUTHORIZED', 401],
+  ['FORBIDDEN', 403],
+  ['FORBIDDEN_FIELD', 403],
+  ['SELF_ADMIN_MUTATION_FORBIDDEN', 403],
+  ['PROTECTED_ROLE', 403],
+  ['SYSTEM_SCHEMA_READ_ONLY', 403],
+  ['COLLECTION_NOT_FOUND', 404],
+  ['FIELD_NOT_FOUND', 404],
+  ['RELATION_NOT_FOUND', 404],
+  ['USER_NOT_FOUND', 404],
+  ['ROLE_NOT_FOUND', 404],
+  ['PERMISSION_NOT_FOUND', 404],
+  ['FILE_NOT_FOUND', 404],
+  ['NOT_FOUND', 404],
+  ['COLLECTION_EXISTS', 409],
+  ['FIELD_EXISTS', 409],
+  ['RELATION_EXISTS', 409],
+  ['COLLECTION_HAS_RELATIONS', 409],
+  ['M2M_JUNCTION_INVALID', 409],
+  ['STORAGE_INVENTORY_LIMIT', 409],
+  ['PUBLIC_ROLE_EXISTS', 409],
+  ['ROLE_IN_USE', 409],
+  ['SCHEMA_METADATA_DRIFT', 409],
+  ['DUPLICATE_KEY', 409],
+  ['FOREIGN_KEY_MISSING', 409],
+  ['FOREIGN_KEY_RESTRICTED', 409],
+  ['RATE_LIMITED', 429],
+  ['PAYLOAD_TOO_LARGE', 413],
+  ['INVALID_QUERY', 400],
+  ['INVALID_PAYLOAD', 400],
+  ['INVALID_PASSWORD', 400],
+  ['INVALID_TOKEN', 400],
+  ['INVALID_ROLE', 400],
+  ['INVALID_PERMISSION', 400],
+  ['INVALID_SCHEMA_PAYLOAD', 400],
+  ['INVALID_AUDIT_EVENT', 400],
+  ['INVALID_ON_DELETE', 400],
+  ['INVALID_STORAGE_KEY', 400],
+  ['INVALID_FILE_CONTENT', 400],
+  ['INVALID_MAIL_MESSAGE', 400],
+  ['STORAGE_NOT_FOUND', 400],
+  ['STORAGE_INVENTORY_UNSUPPORTED', 400],
+  ['UNSUPPORTED_SCHEMA_UPDATE', 400],
+  ['UNSUPPORTED_FIELD_TYPE', 400],
+  ['UNSUPPORTED_FIELD_DEFAULT', 400],
+  ['UNSUPPORTED_PRIMARY_KEY', 400],
+  ['UNSUPPORTED_RELATION_TARGET', 400],
+  ['UNSUPPORTED_RELATION_EXPANSION', 400],
+  ['RELATION_TYPE_MISMATCH', 400],
+  ['DESTRUCTIVE_OPERATION_REQUIRED', 400],
+  ['REQUIRED_FIELD_MISSING', 400],
+  ['FIELD_READ_ONLY', 400],
+  ['FILTER_REQUIRED', 400],
+  ['VALIDATION_FAILED', 400],
+  ['VALIDATION_BULK_LIMIT', 400],
+  ['MAIL_NOT_CONFIGURED', 503],
+  ['STORAGE_INVENTORY_FAILED', 503],
+  ['DATABASE_MIGRATION_REQUIRED', 503],
+  ['DEADLOCK', 503],
+  ['LOCK_WAIT_TIMEOUT', 503],
+  ['CONNECTION_LOST', 503],
+  ['CONNECTION_REFUSED', 503],
+]);
+
+const MYSQL_CODES = new Set([
+  'ER_DUP_ENTRY',
+  'ER_NO_REFERENCED_ROW_2',
+  'ER_ROW_IS_REFERENCED_2',
+  'ER_LOCK_DEADLOCK',
+  'ER_LOCK_WAIT_TIMEOUT',
+  'PROTOCOL_CONNECTION_LOST',
+  'ECONNREFUSED',
+]);
+
+const SAFE_DATABASE_MESSAGES = new Map([
+  ['DUPLICATE_KEY', 'A record with the same unique value already exists'],
+  ['FOREIGN_KEY_MISSING', 'A referenced record does not exist'],
+  ['FOREIGN_KEY_RESTRICTED', 'The record is still referenced and cannot be removed'],
+  ['DEADLOCK', 'The database transaction could not complete; retry the request'],
+  ['LOCK_WAIT_TIMEOUT', 'The database operation timed out waiting for a lock'],
+  ['CONNECTION_LOST', 'Database connection was lost'],
+  ['CONNECTION_REFUSED', 'Database connection is unavailable'],
+]);
+
+function normalizeApiError(error) {
+  if (error?.type === 'entity.too.large') {
+    const normalized = new Error('Request body exceeds the configured upload limit');
+    normalized.code = 'PAYLOAD_TOO_LARGE';
+    normalized.cause = error;
+    return normalized;
+  }
+  if (!MYSQL_CODES.has(error?.code)) return error;
+  const databaseError = normalizeDatabaseError(error);
+  const normalized = new Error(
+    SAFE_DATABASE_MESSAGES.get(databaseError.code) ?? 'Database operation failed',
+  );
+  normalized.code = databaseError.code;
+  normalized.cause = databaseError;
+  return normalized;
+}
+
+export function statusForError(error) {
+  return STATUS_BY_CODE.get(error?.code) ?? 500;
+}
+
+export function errorBody(error, requestId) {
+  const status = statusForError(error);
+  const exposeMessage = status < 500;
+
+  return {
+    errors: [
+      {
+        code: error?.code ?? 'INTERNAL_ERROR',
+        message: exposeMessage ? (error?.message ?? 'Request failed') : 'Internal server error',
+        ...(error?.path ? { path: error.path } : {}),
+        request_id: requestId,
+      },
+    ],
+  };
+}
+
+export function apiErrorHandler(logger = console) {
+  return (error, req, res, _next) => {
+    const normalized = normalizeApiError(error);
+    const status = statusForError(normalized);
+
+    if (status >= 500) {
+      logger.error?.('YunCMS API request failed', {
+        requestId: req.id,
+        code: normalized?.code,
+        error,
+      });
+    }
+
+    res.status(status).json(errorBody(normalized, req.id));
+  };
+}
+
+export { normalizeApiError };

package/src/extensions/discovery.js

@@ -0,0 +1,144 @@
+import { createRequire } from 'node:module';
+import { access, readFile, readdir } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { validateExtensionManifest } from './manifest.js';
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+async function exists(path) {
+  try {
+    await access(path, fsConstants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findPackageRootFromEntry(entryPath, packageName) {
+  let current = dirname(entryPath);
+
+  while (true) {
+    const packagePath = join(current, 'package.json');
+    if (await exists(packagePath)) {
+      try {
+        const packageJson = await readJson(packagePath);
+        if (packageJson.name === packageName) return current;
+      } catch {
+        // Keep walking; a parent package may be the requested package root.
+      }
+    }
+
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  return null;
+}
+
+async function resolveDependencyPackageRoot(rootDir, packageName) {
+  const requireFromProject = createRequire(join(resolve(rootDir), 'package.json'));
+
+  try {
+    return dirname(requireFromProject.resolve(`${packageName}/package.json`));
+  } catch (packageJsonError) {
+    try {
+      const entry = requireFromProject.resolve(packageName);
+      const root = await findPackageRootFromEntry(entry, packageName);
+      if (root) return root;
+    } catch {
+      // Fall through to the original package-json resolution error below.
+    }
+
+    if (/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i.test(packageName)) {
+      const installedRoot = join(resolve(rootDir), 'node_modules', ...packageName.split('/'));
+      const installedPackagePath = join(installedRoot, 'package.json');
+      if (await exists(installedPackagePath)) {
+        const installedPackage = await readJson(installedPackagePath);
+        if (installedPackage.name === packageName) return installedRoot;
+      }
+    }
+
+    const error = new Error(`Unable to resolve installed extension package: ${packageName}`);
+    error.code = 'EXTENSION_PACKAGE_NOT_RESOLVED';
+    error.cause = packageJsonError;
+    throw error;
+  }
+}
+
+async function discoverLocalExtensions(rootDir, localDirectory) {
+  const directory = resolve(rootDir, localDirectory);
+  if (!(await exists(directory))) return [];
+
+  const entries = await readdir(directory, { withFileTypes: true });
+  const discovered = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const packageRoot = join(directory, entry.name);
+    const packagePath = join(packageRoot, 'package.json');
+    if (!(await exists(packagePath))) continue;
+
+    const packageJson = await readJson(packagePath);
+    const manifest = validateExtensionManifest(packageJson, packageRoot);
+    if (manifest) discovered.push({ ...manifest, source: 'local' });
+  }
+
+  return discovered;
+}
+
+async function discoverDependencyExtensions(rootDir) {
+  const rootPackagePath = join(resolve(rootDir), 'package.json');
+  if (!(await exists(rootPackagePath))) return [];
+
+  const rootPackage = await readJson(rootPackagePath);
+  const packageNames = new Set([
+    ...Object.keys(rootPackage.dependencies ?? {}),
+    ...Object.keys(rootPackage.optionalDependencies ?? {}),
+    ...Object.keys(rootPackage.devDependencies ?? {}),
+  ]);
+  const discovered = [];
+
+  for (const packageName of packageNames) {
+    let packageRoot;
+    try {
+      packageRoot = await resolveDependencyPackageRoot(rootDir, packageName);
+    } catch (error) {
+      if (rootPackage.optionalDependencies?.[packageName]) continue;
+      throw error;
+    }
+
+    const packageJson = await readJson(join(packageRoot, 'package.json'));
+    const manifest = validateExtensionManifest(packageJson, packageRoot);
+    if (manifest) discovered.push({ ...manifest, source: 'npm' });
+  }
+
+  return discovered;
+}
+
+export async function discoverExtensions({
+  rootDir = process.cwd(),
+  localDirectory = 'extensions',
+  includeDependencies = true,
+} = {}) {
+  const extensions = [
+    ...(await discoverLocalExtensions(rootDir, localDirectory)),
+    ...(includeDependencies ? await discoverDependencyExtensions(rootDir) : []),
+  ];
+
+  const ids = new Set();
+  for (const extension of extensions) {
+    if (ids.has(extension.id)) {
+      const error = new Error(`Duplicate YunCMS extension id: ${extension.id}`);
+      error.code = 'DUPLICATE_EXTENSION_ID';
+      throw error;
+    }
+    ids.add(extension.id);
+  }
+
+  return extensions.sort((a, b) => a.id.localeCompare(b.id));
+}

package/src/extensions/manifest.js

@@ -0,0 +1,65 @@
+import { resolve, sep } from 'node:path';
+
+const TYPES = new Set(['endpoint', 'hook']);
+const ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+function extensionError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function defaultId(packageName) {
+  const raw = String(packageName ?? '').split('/').at(-1)?.toLowerCase() ?? '';
+  return raw.replace(/^yuncms-extension-/, '').replace(/[^a-z0-9_-]/g, '-');
+}
+
+export function validateExtensionManifest(packageJson, packageRoot) {
+  if (!packageJson || typeof packageJson !== 'object') {
+    throw extensionError('INVALID_EXTENSION_MANIFEST', 'Extension package.json must be an object');
+  }
+  if (!packageJson.yuncms || typeof packageJson.yuncms !== 'object' || Array.isArray(packageJson.yuncms)) {
+    return null;
+  }
+
+  const manifest = packageJson.yuncms;
+  const type = manifest.type;
+  if (!TYPES.has(type)) {
+    throw extensionError(
+      'INVALID_EXTENSION_MANIFEST',
+      `Extension ${packageJson.name ?? '<unnamed>'} has unsupported type: ${String(type)}`,
+    );
+  }
+
+  const id = String(manifest.id ?? defaultId(packageJson.name));
+  if (!ID_PATTERN.test(id)) {
+    throw extensionError(
+      'INVALID_EXTENSION_MANIFEST',
+      `Extension id must match ${ID_PATTERN}: ${id}`,
+    );
+  }
+
+  if (typeof manifest.entry !== 'string' || manifest.entry.trim() === '') {
+    throw extensionError(
+      'INVALID_EXTENSION_MANIFEST',
+      `Extension ${id} requires a yuncms.entry path`,
+    );
+  }
+
+  const root = resolve(packageRoot);
+  const entry = resolve(root, manifest.entry);
+  if (entry !== root && !entry.startsWith(`${root}${sep}`)) {
+    throw extensionError(
+      'INVALID_EXTENSION_MANIFEST',
+      `Extension ${id} entry escapes its package root`,
+    );
+  }
+
+  return Object.freeze({
+    id,
+    type,
+    entry,
+    packageName: packageJson.name ?? id,
+    packageRoot: root,
+  });
+}