@yunsoft/yuncms-api 0.1.0

package/src/extensions/runtime.js

@@ -0,0 +1,121 @@
+import { pathToFileURL } from 'node:url';
+import express from 'express';
+
+import { discoverExtensions } from './discovery.js';
+
+function extensionError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function assertDefinition(definition, manifest) {
+  if (!definition || definition.__yuncms_extension__ !== true || typeof definition.register !== 'function') {
+    throw extensionError(
+      'INVALID_EXTENSION_DEFINITION',
+      `Extension ${manifest.id} must default-export a YunCMS extension definition`,
+    );
+  }
+  if (definition.type !== manifest.type) {
+    throw extensionError(
+      'EXTENSION_TYPE_MISMATCH',
+      `Extension ${manifest.id} manifest type ${manifest.type} does not match definition type ${definition.type}`,
+    );
+  }
+  return definition;
+}
+
+async function importExtension(manifest) {
+  const moduleUrl = pathToFileURL(manifest.entry).href;
+  const imported = await import(moduleUrl);
+  return assertDefinition(imported.default, manifest);
+}
+
+function createBaseContext({ services, database, schemaCache, emitter, storage, logger, env }) {
+  return Object.freeze({
+    services,
+    database,
+    logger,
+    env,
+    emitter,
+    storage,
+    getSchema: () => schemaCache.get(database),
+    getAccountability: (req) => req?.accountability ?? null,
+    serviceOptions: async (req) => ({
+      accountability: req?.accountability,
+      database,
+      schema: req?.context?.schema ?? await schemaCache.get(database),
+      logger,
+      emitter,
+      storage,
+      permissionCache: req?.context?.permissionCache ?? new Map(),
+      requestId: req?.id ?? null,
+    }),
+  });
+}
+
+function hookRegistrationApi(emitter, baseContext) {
+  return Object.freeze({
+    filter(event, handler) {
+      return emitter.registerFilter(event, (payload, eventContext) =>
+        handler(payload, { ...baseContext, ...eventContext }));
+    },
+    action(event, handler) {
+      return emitter.registerAction(event, (payload, eventContext) =>
+        handler(payload, { ...baseContext, ...eventContext }));
+    },
+    init(event, handler) {
+      return emitter.registerInit(event, (eventContext) =>
+        handler({ ...baseContext, ...eventContext }));
+    },
+  });
+}
+
+export async function loadExtensionRuntime({
+  rootDir = process.cwd(),
+  localDirectory = 'extensions',
+  includeDependencies = true,
+  services,
+  database,
+  schemaCache,
+  emitter,
+  storage = null,
+  logger = console,
+  env,
+} = {}) {
+  if (!services || !database || !schemaCache || !emitter) {
+    throw new Error('Extension runtime requires services, database, schemaCache and emitter');
+  }
+
+  const manifests = await discoverExtensions({ rootDir, localDirectory, includeDependencies });
+  const baseContext = createBaseContext({ services, database, 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);
+      logger.info?.(`Loaded YunCMS hook extension: ${manifest.id}`);
+      continue;
+    }
+
+    const router = express.Router();
+    await definition.register(router, baseContext);
+    endpointExtensions.push(Object.freeze({
+      id: manifest.id,
+      router,
+      manifest,
+    }));
+    logger.info?.(`Loaded YunCMS endpoint extension: ${manifest.id}`);
+  }
+
+  return Object.freeze({
+    manifests: Object.freeze(manifests),
+    endpointExtensions: Object.freeze(endpointExtensions),
+    async init(event) {
+      await emitter.init(event, baseContext);
+    },
+  });
+}

package/src/rate-limit.js

@@ -0,0 +1,54 @@
+function rateLimitError(retryAfterSeconds) {
+  const error = new Error('Too many requests');
+  error.code = 'RATE_LIMITED';
+  error.retryAfterSeconds = retryAfterSeconds;
+  return error;
+}
+
+export function createFixedWindowRateLimit({
+  windowMs,
+  max,
+  key = (req) => req.ip || req.socket?.remoteAddress || 'unknown',
+  maxBuckets = 10_000,
+  now = () => Date.now(),
+} = {}) {
+  if (!Number.isInteger(windowMs) || windowMs < 1000) throw new Error('Rate-limit windowMs must be at least 1000');
+  if (!Number.isInteger(max) || max < 1) throw new Error('Rate-limit max must be a positive integer');
+
+  const buckets = new Map();
+
+  function prune(timestamp) {
+    if (buckets.size < maxBuckets) return;
+    for (const [bucketKey, bucket] of buckets) {
+      if (bucket.resetAt <= timestamp) buckets.delete(bucketKey);
+      if (buckets.size < maxBuckets) break;
+    }
+  }
+
+  return (req, res, next) => {
+    const timestamp = now();
+    prune(timestamp);
+    const bucketKey = String(key(req));
+    let bucket = buckets.get(bucketKey);
+
+    if (!bucket || bucket.resetAt <= timestamp) {
+      bucket = { count: 0, resetAt: timestamp + windowMs };
+      buckets.set(bucketKey, bucket);
+    }
+
+    bucket.count += 1;
+    const remaining = Math.max(0, max - bucket.count);
+    const retryAfterSeconds = Math.max(1, Math.ceil((bucket.resetAt - timestamp) / 1000));
+    res.set('x-ratelimit-limit', String(max));
+    res.set('x-ratelimit-remaining', String(remaining));
+    res.set('x-ratelimit-reset', String(Math.ceil(bucket.resetAt / 1000)));
+
+    if (bucket.count > max) {
+      res.set('retry-after', String(retryAfterSeconds));
+      next(rateLimitError(retryAfterSeconds));
+      return;
+    }
+
+    next();
+  };
+}

package/src/routes/audit.js

@@ -0,0 +1,45 @@
+import express from 'express';
+
+import { serviceOptionsFromRequest } from '../service-options.js';
+
+function auditService(req) {
+  const Service = req.context.services.AuditService;
+  return new Service(serviceOptionsFromRequest(req));
+}
+
+function integerQuery(value, fallback, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) {
+  if (value == null || value === '') return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    const error = new Error('Invalid audit pagination value');
+    error.code = 'INVALID_QUERY';
+    throw error;
+  }
+  return parsed;
+}
+
+export function createAuditRouter() {
+  const router = express.Router();
+
+  router.get('/', async (req, res) => {
+    const data = await auditService(req).readMany({
+      limit: integerQuery(req.query.limit, 100, { min: 1, max: 500 }),
+      offset: integerQuery(req.query.offset, 0, { min: 0 }),
+      collection: req.query.collection || null,
+      user: req.query.user || null,
+    });
+    res.json({ data });
+  });
+
+  router.post('/cleanup', async (req, res) => {
+    const defaults = req.context.env?.audit ?? {};
+    const data = await auditService(req).cleanup({
+      retentionDays: req.body?.retentionDays ?? defaults.retentionDays,
+      batchSize: req.body?.batchSize ?? defaults.cleanupBatchSize,
+      maxBatches: req.body?.maxBatches ?? defaults.cleanupMaxBatches,
+    });
+    res.json({ data });
+  });
+
+  return router;
+}

package/src/routes/auth.js

@@ -0,0 +1,179 @@
+import express from 'express';
+
+import { createFixedWindowRateLimit } from '../rate-limit.js';
+import { serviceOptionsFromRequest } from '../service-options.js';
+
+function service(req, name) {
+  const Service = req.context.services[name];
+  return new Service(serviceOptionsFromRequest(req));
+}
+
+function authService(req) {
+  return service(req, 'AuthService');
+}
+
+function authTokensService(req) {
+  return service(req, 'AuthTokensService');
+}
+
+function apiTokensService(req) {
+  return service(req, 'ApiTokensService');
+}
+
+function usersService(req) {
+  return service(req, 'UsersService');
+}
+
+function requireSessionAuthentication(req) {
+  if (req.authMethod !== 'session' || !req.authToken) {
+    const error = new Error('Session access token is required');
+    error.code = 'UNAUTHORIZED';
+    throw error;
+  }
+}
+
+function requireMailer(mailer) {
+  if (mailer) return mailer;
+  const error = new Error('SMTP mail delivery is not configured');
+  error.code = 'MAIL_NOT_CONFIGURED';
+  throw error;
+}
+
+function actionUrl(config, action, token) {
+  return `${config.auth.publicUrl}/?auth_action=${encodeURIComponent(action)}&token=${encodeURIComponent(token)}`;
+}
+
+function noStore(req, res, next) {
+  res.set('cache-control', 'no-store');
+  res.set('pragma', 'no-cache');
+  next();
+}
+
+export function createAuthRouter({ mailer = null, config = null, logger = console } = {}) {
+  const router = express.Router();
+  const limits = config?.auth?.rateLimit ?? {};
+  const loginLimit = createFixedWindowRateLimit({
+    windowMs: limits.loginWindowMs ?? 60_000,
+    max: limits.loginMax ?? 10,
+  });
+  const refreshLimit = createFixedWindowRateLimit({
+    windowMs: limits.refreshWindowMs ?? 60_000,
+    max: limits.refreshMax ?? 30,
+  });
+  const actionLimit = createFixedWindowRateLimit({
+    windowMs: limits.actionWindowMs ?? 15 * 60_000,
+    max: limits.actionMax ?? 5,
+  });
+
+  router.use(noStore);
+
+  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 });
+  });
+
+  router.post('/refresh', refreshLimit, async (req, res) => {
+    const result = await authService(req).refresh(req.body?.refresh_token);
+    res.json({ data: result });
+  });
+
+  router.post('/logout', async (req, res) => {
+    requireSessionAuthentication(req);
+    await authService(req).logout(req.authToken);
+    res.status(204).end();
+  });
+
+  router.post('/logout-all', async (req, res) => {
+    requireSessionAuthentication(req);
+    await authService(req).logoutAll();
+    res.status(204).end();
+  });
+
+  router.post('/password-reset/request', actionLimit, async (req, res) => {
+    const transport = requireMailer(mailer);
+    const result = await authTokensService(req).requestPasswordReset(req.body?.email);
+
+    if (result) {
+      try {
+        const url = actionUrl(config, 'reset', result.token);
+        await transport.send({
+          to: String(req.body.email).trim(),
+          subject: 'Reset your YunCMS password',
+          text: `A password reset was requested for your YunCMS account.\n\nOpen this link to choose a new password:\n${url}\n\nIf you did not request this, you can ignore this message.`,
+        });
+      } catch (error) {
+        logger.error?.('YunCMS password reset mail delivery failed', {
+          requestId: req.id,
+          code: error?.code,
+          message: error?.message,
+        });
+      }
+    }
+
+    res.status(202).json({ data: { accepted: true } });
+  });
+
+  router.post('/password-reset/confirm', actionLimit, async (req, res) => {
+    await authTokensService(req).resetPassword(req.body?.token, req.body?.password);
+    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 userId = req.body?.user ?? req.accountability.user;
+    const user = await usersService(req).readOne(userId);
+    if (!user) {
+      const error = new Error(`User not found: ${userId}`);
+      error.code = 'USER_NOT_FOUND';
+      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.`,
+    });
+    res.status(202).json({ data: { accepted: true } });
+  });
+
+  router.post('/email-verification/confirm', actionLimit, async (req, res) => {
+    await authTokensService(req).verifyEmail(req.body?.token);
+    res.status(204).end();
+  });
+
+  router.get('/tokens', async (req, res) => {
+    const data = await apiTokensService(req).readMany();
+    res.json({ data });
+  });
+
+  router.post('/tokens', async (req, res) => {
+    const data = await apiTokensService(req).createOne(req.body ?? {});
+    res.status(201).json({ data });
+  });
+
+  router.delete('/tokens/:id', async (req, res) => {
+    const deleted = await apiTokensService(req).deleteOne(req.params.id);
+    if (!deleted) {
+      const error = new Error('API token not found');
+      error.code = 'NOT_FOUND';
+      throw error;
+    }
+    res.status(204).end();
+  });
+
+  return router;
+}
+
+export { actionUrl, noStore, requireMailer, requireSessionAuthentication };

package/src/routes/files.js

@@ -0,0 +1,98 @@
+import express from 'express';
+
+import { serviceOptionsFromRequest } from '../service-options.js';
+
+function filesService(req) {
+  const Service = req.context.services.FilesService;
+  return new Service(serviceOptionsFromRequest(req));
+}
+
+function reconciliationService(req) {
+  const Service = req.context.services.FileReconciliationService;
+  return new Service(serviceOptionsFromRequest(req));
+}
+
+function notFound(id) {
+  const error = new Error(`File not found: ${id}`);
+  error.code = 'FILE_NOT_FOUND';
+  return error;
+}
+
+function decodeFilenameHeader(value) {
+  if (!value) return value;
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    const error = new Error('Encoded upload filename is invalid');
+    error.code = 'INVALID_PAYLOAD';
+    throw error;
+  }
+}
+
+function attachmentHeader(filename) {
+  const safe = String(filename || 'download')
+    .replace(/[\r\n]/g, '')
+    .replace(/["\\]/g, '_');
+  return `attachment; filename="${safe.replace(/[^\x20-\x7e]/g, '_')}"; filename*=UTF-8''${encodeURIComponent(safe)}`;
+}
+
+export function createFilesRouter({ maxUploadBytes = 25 * 1024 * 1024 } = {}) {
+  const router = express.Router();
+  const rawUpload = express.raw({ type: 'application/octet-stream', limit: maxUploadBytes });
+
+  router.get('/', async (req, res) => {
+    res.json({ data: await filesService(req).readMany() });
+  });
+
+  router.post('/', rawUpload, async (req, res) => {
+    const filenameDownload = decodeFilenameHeader(req.get('x-filename'));
+    const title = req.get('x-title') || null;
+    const mimetype = req.get('x-mimetype') || 'application/octet-stream';
+    const storage = req.query.storage || 'local';
+    const data = await filesService(req).createOne({
+      contents: req.body,
+      filenameDownload,
+      title,
+      mimetype,
+      storage,
+    });
+    res.status(201).json({ data });
+  });
+
+  router.post('/reconcile', async (req, res) => {
+    const data = await reconciliationService(req).scan({
+      storage: req.body?.storage ?? 'local',
+      deleteOrphans: req.body?.deleteOrphans === true,
+      minimumAgeMs: req.body?.minimumAgeMs,
+    });
+    res.json({ data });
+  });
+
+  router.get('/:id', async (req, res) => {
+    const data = await filesService(req).readOne(req.params.id);
+    if (!data) throw notFound(req.params.id);
+    res.json({ data });
+  });
+
+  router.get('/:id/content', async (req, res) => {
+    const result = await filesService(req).readContent(req.params.id);
+    res.set('content-type', result.file.mimetype || 'application/octet-stream');
+    res.set('content-length', String(result.contents.byteLength));
+    res.set('content-disposition', attachmentHeader(result.file.filename_download));
+    res.send(result.contents);
+  });
+
+  router.patch('/:id', async (req, res) => {
+    const data = await filesService(req).updateOne(req.params.id, req.body ?? {});
+    res.json({ data });
+  });
+
+  router.delete('/:id', async (req, res) => {
+    await filesService(req).deleteOne(req.params.id);
+    res.status(204).end();
+  });
+
+  return router;
+}
+
+export { attachmentHeader, decodeFilenameHeader };

package/src/routes/items.js

@@ -0,0 +1,75 @@
+import express from 'express';
+import { readManyWithRelations, readOneWithRelations } from '@yunsoft/yuncms-core';
+
+import { serviceOptionsFromRequest } from '../service-options.js';
+
+export function createItemsRouter() {
+  const router = express.Router();
+
+  router.get('/:collection', async (req, res) => {
+    const Service = req.context.services.ItemsService;
+    const result = await readManyWithRelations({
+      collection: req.params.collection,
+      query: req.query,
+      options: serviceOptionsFromRequest(req),
+      ItemsServiceClass: Service,
+    });
+    res.json(result);
+  });
+
+  router.get('/:collection/:id', async (req, res) => {
+    const Service = req.context.services.ItemsService;
+    const data = await readOneWithRelations({
+      collection: req.params.collection,
+      id: req.params.id,
+      query: req.query,
+      options: serviceOptionsFromRequest(req),
+      ItemsServiceClass: Service,
+    });
+
+    if (!data) {
+      const error = new Error('Item not found');
+      error.code = 'NOT_FOUND';
+      throw error;
+    }
+
+    res.json({ data });
+  });
+
+  router.post('/:collection', async (req, res) => {
+    const Service = req.context.services.ItemsService;
+    const service = new Service(req.params.collection, serviceOptionsFromRequest(req));
+    const data = await service.createOne(req.body);
+    res.status(201).json({ data });
+  });
+
+  router.patch('/:collection/:id', async (req, res) => {
+    const Service = req.context.services.ItemsService;
+    const service = new Service(req.params.collection, serviceOptionsFromRequest(req));
+    const data = await service.updateOne(req.params.id, req.body);
+
+    if (!data) {
+      const error = new Error('Item not found or not accessible');
+      error.code = 'NOT_FOUND';
+      throw error;
+    }
+
+    res.json({ data });
+  });
+
+  router.delete('/:collection/:id', async (req, res) => {
+    const Service = req.context.services.ItemsService;
+    const service = new Service(req.params.collection, serviceOptionsFromRequest(req));
+    const deleted = await service.deleteOne(req.params.id);
+
+    if (!deleted) {
+      const error = new Error('Item not found or not accessible');
+      error.code = 'NOT_FOUND';
+      throw error;
+    }
+
+    res.status(204).end();
+  });
+
+  return router;
+}

package/src/routes/permissions.js

@@ -0,0 +1,45 @@
+import express from 'express';
+
+import { serviceOptionsFromRequest } from '../service-options.js';
+
+function permissionsService(req) {
+  const Service = req.context.services.PermissionsService;
+  return new Service(serviceOptionsFromRequest(req));
+}
+
+function notFound(id) {
+  const error = new Error(`Permission not found: ${id}`);
+  error.code = 'PERMISSION_NOT_FOUND';
+  return error;
+}
+
+export function createPermissionsRouter() {
+  const router = express.Router();
+
+  router.get('/', async (req, res) => {
+    res.json({ data: await permissionsService(req).readMany() });
+  });
+
+  router.post('/', async (req, res) => {
+    const data = await permissionsService(req).createOne(req.body ?? {});
+    res.status(201).json({ data });
+  });
+
+  router.get('/:id', async (req, res) => {
+    const data = await permissionsService(req).readOne(req.params.id);
+    if (!data) throw notFound(req.params.id);
+    res.json({ data });
+  });
+
+  router.patch('/:id', async (req, res) => {
+    const data = await permissionsService(req).updateOne(req.params.id, req.body ?? {});
+    res.json({ data });
+  });
+
+  router.delete('/:id', async (req, res) => {
+    await permissionsService(req).deleteOne(req.params.id);
+    res.status(204).end();
+  });
+
+  return router;
+}

package/src/routes/roles.js

@@ -0,0 +1,45 @@
+import express from 'express';
+
+import { serviceOptionsFromRequest } from '../service-options.js';
+
+function rolesService(req) {
+  const Service = req.context.services.RolesService;
+  return new Service(serviceOptionsFromRequest(req));
+}
+
+function notFound(id) {
+  const error = new Error(`Role not found: ${id}`);
+  error.code = 'ROLE_NOT_FOUND';
+  return error;
+}
+
+export function createRolesRouter() {
+  const router = express.Router();
+
+  router.get('/', async (req, res) => {
+    res.json({ data: await rolesService(req).readMany() });
+  });
+
+  router.post('/', async (req, res) => {
+    const data = await rolesService(req).createOne(req.body ?? {});
+    res.status(201).json({ data });
+  });
+
+  router.get('/:id', async (req, res) => {
+    const data = await rolesService(req).readOne(req.params.id);
+    if (!data) throw notFound(req.params.id);
+    res.json({ data });
+  });
+
+  router.patch('/:id', async (req, res) => {
+    const data = await rolesService(req).updateOne(req.params.id, req.body ?? {});
+    res.json({ data });
+  });
+
+  router.delete('/:id', async (req, res) => {
+    await rolesService(req).deleteOne(req.params.id);
+    res.status(204).end();
+  });
+
+  return router;
+}