@yunsoft/yuncms-core 0.1.0

package/src/schema-metadata-repository.js

@@ -0,0 +1,284 @@
+function encodeJson(value) {
+  return value == null ? null : JSON.stringify(value);
+}
+
+export class SchemaMetadataRepository {
+  constructor(database) {
+    if (!database) throw new Error('Database handle is required');
+    this.database = database;
+  }
+
+  async listCollections() {
+    const [rows] = await this.database.query(
+      `SELECT collection, primary_key, note, singleton, hidden, \`system\`, metadata, created_at, updated_at
+       FROM yuncms_collections
+       ORDER BY collection ASC`,
+    );
+    return rows;
+  }
+
+  async readCollection(collection) {
+    const [rows] = await this.database.query(
+      `SELECT collection, primary_key, note, singleton, hidden, \`system\`, metadata, created_at, updated_at
+       FROM yuncms_collections
+       WHERE collection = ?
+       LIMIT 1`,
+      [collection],
+    );
+    return rows[0] ?? null;
+  }
+
+  async createCollection({
+    collection,
+    primaryKey = 'id',
+    note = null,
+    singleton = false,
+    hidden = false,
+    system = false,
+    metadata = null,
+  }) {
+    await this.database.query(
+      `INSERT INTO yuncms_collections
+       (collection, primary_key, note, singleton, hidden, \`system\`, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [
+        collection,
+        primaryKey,
+        note,
+        singleton ? 1 : 0,
+        hidden ? 1 : 0,
+        system ? 1 : 0,
+        encodeJson(metadata),
+      ],
+    );
+    return this.readCollection(collection);
+  }
+
+  async updateCollectionMetadata(collection, patch = {}) {
+    const assignments = [];
+    const params = [];
+
+    if (Object.hasOwn(patch, 'note')) {
+      assignments.push('note = ?');
+      params.push(patch.note ?? null);
+    }
+    if (Object.hasOwn(patch, 'singleton')) {
+      assignments.push('singleton = ?');
+      params.push(patch.singleton ? 1 : 0);
+    }
+    if (Object.hasOwn(patch, 'hidden')) {
+      assignments.push('hidden = ?');
+      params.push(patch.hidden ? 1 : 0);
+    }
+    if (Object.hasOwn(patch, 'metadata')) {
+      assignments.push('metadata = ?');
+      params.push(encodeJson(patch.metadata));
+    }
+
+    if (assignments.length === 0) return this.readCollection(collection);
+    params.push(collection);
+    await this.database.query(
+      `UPDATE yuncms_collections SET ${assignments.join(', ')} WHERE collection = ?`,
+      params,
+    );
+    return this.readCollection(collection);
+  }
+
+  async deleteCollection(collection) {
+    const [result] = await this.database.query(
+      'DELETE FROM yuncms_collections WHERE collection = ?',
+      [collection],
+    );
+    return result.affectedRows;
+  }
+
+  async listFields(collection) {
+    const [rows] = await this.database.query(
+      `SELECT id, collection, field, type, required, readonly, hidden, sort, interface, options, schema_metadata,
+              created_at, updated_at
+       FROM yuncms_fields
+       WHERE collection = ?
+       ORDER BY COALESCE(sort, 2147483647), id ASC`,
+      [collection],
+    );
+    return rows;
+  }
+
+  async readField(collection, field) {
+    const [rows] = await this.database.query(
+      `SELECT id, collection, field, type, required, readonly, hidden, sort, interface, options, schema_metadata,
+              created_at, updated_at
+       FROM yuncms_fields
+       WHERE collection = ? AND field = ?
+       LIMIT 1`,
+      [collection, field],
+    );
+    return rows[0] ?? null;
+  }
+
+  async createField({
+    collection,
+    field,
+    type,
+    required = false,
+    readonly = false,
+    hidden = false,
+    sort = null,
+    interface: fieldInterface = null,
+    options = null,
+    schemaMetadata = null,
+  }) {
+    await this.database.query(
+      `INSERT INTO yuncms_fields
+       (collection, field, type, required, readonly, hidden, sort, interface, options, schema_metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        collection,
+        field,
+        type,
+        required ? 1 : 0,
+        readonly ? 1 : 0,
+        hidden ? 1 : 0,
+        sort,
+        fieldInterface,
+        encodeJson(options),
+        encodeJson(schemaMetadata),
+      ],
+    );
+    return this.readField(collection, field);
+  }
+
+  async updateFieldMetadata(collection, field, patch = {}) {
+    const assignments = [];
+    const params = [];
+
+    if (Object.hasOwn(patch, 'readonly')) {
+      assignments.push('readonly = ?');
+      params.push(patch.readonly ? 1 : 0);
+    }
+    if (Object.hasOwn(patch, 'hidden')) {
+      assignments.push('hidden = ?');
+      params.push(patch.hidden ? 1 : 0);
+    }
+    if (Object.hasOwn(patch, 'sort')) {
+      assignments.push('sort = ?');
+      params.push(patch.sort ?? null);
+    }
+    if (Object.hasOwn(patch, 'interface')) {
+      assignments.push('interface = ?');
+      params.push(patch.interface ?? null);
+    }
+    if (Object.hasOwn(patch, 'options')) {
+      assignments.push('options = ?');
+      params.push(encodeJson(patch.options));
+    }
+
+    if (assignments.length === 0) return this.readField(collection, field);
+    params.push(collection, field);
+    await this.database.query(
+      `UPDATE yuncms_fields SET ${assignments.join(', ')} WHERE collection = ? AND field = ?`,
+      params,
+    );
+    return this.readField(collection, field);
+  }
+
+  async updateFieldPhysicalMetadata(collection, field, { required, schemaMetadata } = {}) {
+    const assignments = [];
+    const params = [];
+
+    if (required !== undefined) {
+      assignments.push('required = ?');
+      params.push(required ? 1 : 0);
+    }
+    if (schemaMetadata !== undefined) {
+      assignments.push('schema_metadata = ?');
+      params.push(encodeJson(schemaMetadata));
+    }
+
+    if (assignments.length === 0) return this.readField(collection, field);
+    params.push(collection, field);
+    await this.database.query(
+      `UPDATE yuncms_fields SET ${assignments.join(', ')} WHERE collection = ? AND field = ?`,
+      params,
+    );
+    return this.readField(collection, field);
+  }
+
+  async deleteField(collection, field) {
+    const [result] = await this.database.query(
+      'DELETE FROM yuncms_fields WHERE collection = ? AND field = ?',
+      [collection, field],
+    );
+    return result.affectedRows;
+  }
+
+  async listRelations() {
+    const [rows] = await this.database.query(
+      `SELECT id, many_collection, many_field, one_collection, one_field, junction_collection,
+              junction_field, on_delete, metadata, created_at
+       FROM yuncms_relations
+       ORDER BY many_collection, many_field`,
+    );
+    return rows;
+  }
+
+  async listRelationsForOne(oneCollection) {
+    const [rows] = await this.database.query(
+      `SELECT id, many_collection, many_field, one_collection, one_field, junction_collection,
+              junction_field, on_delete, metadata, created_at
+       FROM yuncms_relations
+       WHERE one_collection = ?
+       ORDER BY many_collection, many_field`,
+      [oneCollection],
+    );
+    return rows;
+  }
+
+  async readRelation(manyCollection, manyField) {
+    const [rows] = await this.database.query(
+      `SELECT id, many_collection, many_field, one_collection, one_field, junction_collection,
+              junction_field, on_delete, metadata, created_at
+       FROM yuncms_relations
+       WHERE many_collection = ? AND many_field = ?
+       LIMIT 1`,
+      [manyCollection, manyField],
+    );
+    return rows[0] ?? null;
+  }
+
+  async createRelation({
+    manyCollection,
+    manyField,
+    oneCollection,
+    oneField = null,
+    junctionCollection = null,
+    junctionField = null,
+    onDelete = 'RESTRICT',
+    metadata = null,
+  }) {
+    await this.database.query(
+      `INSERT INTO yuncms_relations
+       (many_collection, many_field, one_collection, one_field, junction_collection, junction_field, on_delete, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        manyCollection,
+        manyField,
+        oneCollection,
+        oneField,
+        junctionCollection,
+        junctionField,
+        onDelete,
+        encodeJson(metadata),
+      ],
+    );
+    return this.readRelation(manyCollection, manyField);
+  }
+
+  async deleteRelation(manyCollection, manyField) {
+    const [result] = await this.database.query(
+      'DELETE FROM yuncms_relations WHERE many_collection = ? AND many_field = ?',
+      [manyCollection, manyField],
+    );
+    return result.affectedRows;
+  }
+}

package/src/schema-version.js

@@ -0,0 +1,21 @@
+export async function readSchemaVersion(database) {
+  const [rows] = await database.query('SELECT version FROM yuncms_schema_state WHERE id = 1 LIMIT 1');
+  if (!rows?.[0]) {
+    const error = new Error('YunCMS schema state is missing');
+    error.code = 'SCHEMA_STATE_MISSING';
+    throw error;
+  }
+
+  return Number(rows[0].version);
+}
+
+export async function incrementSchemaVersion(database) {
+  const [result] = await database.query('UPDATE yuncms_schema_state SET version = version + 1 WHERE id = 1');
+  if (result.affectedRows !== 1) {
+    const error = new Error('Could not update YunCMS schema version');
+    error.code = 'SCHEMA_STATE_MISSING';
+    throw error;
+  }
+
+  return readSchemaVersion(database);
+}

package/src/schema.js

@@ -0,0 +1,82 @@
+import { SchemaMetadataRepository } from './schema-metadata-repository.js';
+import { readSchemaVersion } from './schema-version.js';
+
+export async function loadSchemaSnapshot(database) {
+  const version = await readSchemaVersion(database);
+  const repository = new SchemaMetadataRepository(database);
+  const [collections, relations] = await Promise.all([
+    repository.listCollections(),
+    repository.listRelations(),
+  ]);
+
+  const fieldsByCollection = new Map();
+  await Promise.all(
+    collections.map(async (collection) => {
+      fieldsByCollection.set(
+        collection.collection,
+        await repository.listFields(collection.collection),
+      );
+    }),
+  );
+
+  const relationByManyField = new Map(
+    relations.map((relation) => [
+      `${relation.many_collection}.${relation.many_field}`,
+      relation,
+    ]),
+  );
+
+  return Object.freeze({
+    version,
+    collections: Object.freeze(
+      Object.fromEntries(
+        collections.map((collection) => [
+          collection.collection,
+          Object.freeze({
+            ...collection,
+            fields: Object.freeze(
+              Object.fromEntries(
+                (fieldsByCollection.get(collection.collection) ?? []).map((field) => [field.field, field]),
+              ),
+            ),
+          }),
+        ]),
+      ),
+    ),
+    relations: Object.freeze(relations),
+    relationByManyField,
+  });
+}
+
+export class SchemaCache {
+  constructor({ versionCheckTtlMs = 250 } = {}) {
+    this.versionCheckTtlMs = versionCheckTtlMs;
+    this.snapshot = null;
+    this.lastVersionCheckAt = 0;
+  }
+
+  async get(database, { force = false } = {}) {
+    const now = Date.now();
+
+    if (!force && this.snapshot && now - this.lastVersionCheckAt < this.versionCheckTtlMs) {
+      return this.snapshot;
+    }
+
+    const currentVersion = await readSchemaVersion(database);
+    this.lastVersionCheckAt = now;
+
+    if (!force && this.snapshot?.version === currentVersion) {
+      return this.snapshot;
+    }
+
+    const snapshot = await loadSchemaSnapshot(database);
+    this.snapshot = snapshot;
+    this.lastVersionCheckAt = Date.now();
+    return snapshot;
+  }
+
+  clear() {
+    this.snapshot = null;
+    this.lastVersionCheckAt = 0;
+  }
+}

package/src/services/api-tokens-service.js

@@ -0,0 +1,117 @@
+import { randomUUID } from 'node:crypto';
+
+import { createOpaqueToken } from '../auth/tokens.js';
+import { BaseService } from './base-service.js';
+
+function forbidden(message) {
+  const error = new Error(message);
+  error.code = 'FORBIDDEN';
+  return error;
+}
+
+function targetUser(accountability, requestedUser = null) {
+  if (accountability.admin === true || accountability.system === true) {
+    const user = requestedUser ?? accountability.user;
+    if (!user) {
+      const error = new Error('API token user is required');
+      error.code = 'INVALID_PAYLOAD';
+      throw error;
+    }
+    return user;
+  }
+
+  if (!accountability.user) throw forbidden('Authenticated user is required');
+  if (requestedUser && requestedUser !== accountability.user) {
+    throw forbidden('API tokens can only be managed for the authenticated user');
+  }
+  return accountability.user;
+}
+
+function parseExpiry(value) {
+  if (value == null || value === '') return null;
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    const error = new Error('API token expiry is invalid');
+    error.code = 'INVALID_PAYLOAD';
+    throw error;
+  }
+  if (date.getTime() <= Date.now()) {
+    const error = new Error('API token expiry must be in the future');
+    error.code = 'INVALID_PAYLOAD';
+    throw error;
+  }
+  return date;
+}
+
+export class ApiTokensService extends BaseService {
+  async readMany(userId = null) {
+    const user = targetUser(this.accountability, userId);
+    const [rows] = await this.database.query(
+      `SELECT id, user, name, expires_at, last_used_at, created_at
+       FROM yuncms_api_tokens
+       WHERE user = ?
+       ORDER BY created_at DESC`,
+      [user],
+    );
+    return rows;
+  }
+
+  async createOne(input = {}) {
+    const user = targetUser(this.accountability, input.user ?? null);
+    if (!input.name || typeof input.name !== 'string' || input.name.trim().length === 0) {
+      const error = new Error('API token name is required');
+      error.code = 'INVALID_PAYLOAD';
+      throw error;
+    }
+    const name = input.name.trim();
+    if (name.length > 100) {
+      const error = new Error('API token name cannot exceed 100 characters');
+      error.code = 'INVALID_PAYLOAD';
+      throw error;
+    }
+    const expiresAt = parseExpiry(input.expires_at ?? input.expiresAt ?? null);
+
+    const [userRows] = await this.database.query(
+      `SELECT id FROM yuncms_users WHERE id = ? AND status = 'active' LIMIT 1`,
+      [user],
+    );
+    if (!userRows[0]) {
+      const error = new Error(`Unknown or inactive user: ${user}`);
+      error.code = 'USER_NOT_FOUND';
+      throw error;
+    }
+
+    const id = randomUUID();
+    const generated = createOpaqueToken('api', { bytes: 40 });
+    await this.database.query(
+      `INSERT INTO yuncms_api_tokens (id, user, name, token_hash, expires_at)
+       VALUES (?, ?, ?, ?, ?)`,
+      [id, user, name, generated.hash, expiresAt],
+    );
+
+    return {
+      id,
+      user,
+      name,
+      token: generated.token,
+      expires_at: expiresAt,
+    };
+  }
+
+  async deleteOne(id, userId = null) {
+    const user = targetUser(this.accountability, userId);
+    let sql = 'DELETE FROM yuncms_api_tokens WHERE id = ?';
+    const params = [id];
+
+    if (this.accountability.admin !== true && this.accountability.system !== true) {
+      sql += ' AND user = ?';
+      params.push(user);
+    } else if (userId) {
+      sql += ' AND user = ?';
+      params.push(user);
+    }
+
+    const [result] = await this.database.query(sql, params);
+    return result.affectedRows > 0;
+  }
+}

package/src/services/audit-service.js

@@ -0,0 +1,182 @@
+import { BaseService } from './base-service.js';
+
+const SENSITIVE_KEY = /(password|passwd|token|secret|authorization|cookie|api[_-]?key|credential)/i;
+const MAX_DEPTH = 12;
+const DEFAULT_RETENTION_DAYS = 90;
+const DEFAULT_CLEANUP_BATCH_SIZE = 1000;
+
+function auditError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function assertAuditReader(accountability) {
+  if (accountability.admin === true || accountability.system === true) return;
+  throw auditError('FORBIDDEN', 'Audit log access requires administrator accountability');
+}
+
+function boundedInteger(value, fallback, { min, max, label }) {
+  const normalized = value ?? fallback;
+  if (!Number.isInteger(normalized) || normalized < min || normalized > max) {
+    throw auditError('INVALID_PAYLOAD', `${label} must be an integer between ${min} and ${max}`);
+  }
+  return normalized;
+}
+
+export function redactAuditValue(value, depth = 0, seen = new WeakSet()) {
+  if (value == null || typeof value !== 'object') return value;
+  if (depth >= MAX_DEPTH) return '[MAX_DEPTH]';
+  if (seen.has(value)) return '[CIRCULAR]';
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    const result = value.map((entry) => redactAuditValue(entry, depth + 1, seen));
+    seen.delete(value);
+    return result;
+  }
+
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    result[key] = SENSITIVE_KEY.test(key)
+      ? '[REDACTED]'
+      : redactAuditValue(entry, depth + 1, seen);
+  }
+  seen.delete(value);
+  return result;
+}
+
+function decodePayload(value) {
+  if (value == null || typeof value === 'object') return value ?? null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+export class AuditService extends BaseService {
+  async record({
+    user = this.accountability.user ?? null,
+    action,
+    collection = null,
+    itemKey = null,
+    requestId = this.requestId ?? null,
+    ip = null,
+    payload = null,
+  } = {}) {
+    if (typeof action !== 'string' || !action.trim() || action.length > 32) {
+      throw auditError('INVALID_AUDIT_EVENT', 'Audit action is required and must not exceed 32 characters');
+    }
+    if (collection != null && (typeof collection !== 'string' || collection.length > 64)) {
+      throw auditError('INVALID_AUDIT_EVENT', 'Audit collection is invalid');
+    }
+    if (itemKey != null && String(itemKey).length > 191) {
+      throw auditError('INVALID_AUDIT_EVENT', 'Audit item key is too long');
+    }
+
+    const redacted = payload == null ? null : redactAuditValue(payload);
+    const [result] = await this.database.query(
+      `INSERT INTO yuncms_audit_log
+       (user, action, collection, item_key, request_id, ip, payload)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [
+        user,
+        action.trim(),
+        collection,
+        itemKey == null ? null : String(itemKey),
+        requestId == null ? null : String(requestId).slice(0, 64),
+        ip == null ? null : String(ip).slice(0, 45),
+        redacted == null ? null : JSON.stringify(redacted),
+      ],
+    );
+    return result.insertId ?? null;
+  }
+
+  async readMany({ limit = 100, offset = 0, collection = null, user = null } = {}) {
+    assertAuditReader(this.accountability);
+    const safeLimit = Number.isInteger(limit) ? Math.min(Math.max(limit, 1), 500) : 100;
+    const safeOffset = Number.isInteger(offset) ? Math.max(offset, 0) : 0;
+    const where = [];
+    const params = [];
+
+    if (collection) {
+      where.push('collection = ?');
+      params.push(collection);
+    }
+    if (user) {
+      where.push('user = ?');
+      params.push(user);
+    }
+    const whereSql = where.length > 0 ? ` WHERE ${where.join(' AND ')}` : '';
+
+    const [rows] = await this.database.query(
+      `SELECT id, user, action, collection, item_key, request_id, ip, payload, created_at
+       FROM yuncms_audit_log${whereSql}
+       ORDER BY id DESC
+       LIMIT ? OFFSET ?`,
+      [...params, safeLimit, safeOffset],
+    );
+    return rows.map((row) => ({ ...row, payload: decodePayload(row.payload) }));
+  }
+
+  async cleanup({
+    retentionDays = DEFAULT_RETENTION_DAYS,
+    batchSize = DEFAULT_CLEANUP_BATCH_SIZE,
+    maxBatches = 100,
+  } = {}) {
+    assertAuditReader(this.accountability);
+    const days = boundedInteger(retentionDays, DEFAULT_RETENTION_DAYS, {
+      min: 1,
+      max: 3650,
+      label: 'Audit retention days',
+    });
+    const size = boundedInteger(batchSize, DEFAULT_CLEANUP_BATCH_SIZE, {
+      min: 1,
+      max: 5000,
+      label: 'Audit cleanup batch size',
+    });
+    const batchesLimit = boundedInteger(maxBatches, 100, {
+      min: 1,
+      max: 1000,
+      label: 'Audit cleanup max batches',
+    });
+    const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+
+    let deleted = 0;
+    let batches = 0;
+    let complete = false;
+
+    while (batches < batchesLimit) {
+      const [result] = await this.database.query(
+        `DELETE FROM yuncms_audit_log
+         WHERE created_at < ?
+         ORDER BY id ASC
+         LIMIT ?`,
+        [cutoff, size],
+      );
+      const affected = Number(result.affectedRows ?? 0);
+      deleted += affected;
+      batches += 1;
+      if (affected < size) {
+        complete = true;
+        break;
+      }
+    }
+
+    return {
+      retentionDays: days,
+      batchSize: size,
+      maxBatches: batchesLimit,
+      cutoff,
+      deleted,
+      batches,
+      complete,
+    };
+  }
+}
+
+export {
+  DEFAULT_CLEANUP_BATCH_SIZE,
+  DEFAULT_RETENTION_DAYS,
+};