@yunsoft/yuncms-core 0.1.3 → 0.1.6

package/src/index.js

@@ -1,10 +1,24 @@
 export { DEFAULT_SERVER_PORT, loadConfig, loadEnvFileIfPresent } from './config.js';
+export { isCacheStore, MemoryCacheStore } from './cache.js';
+export {
+  RedisClient,
+  RedisCacheStore,
+  RedisFixedWindowStore,
+  parseRedisUrl,
+  redactRedisUrl,
+} from './redis.js';
 export { createDatabasePool, pingDatabase, closeDatabasePool } from './database.js';
 export { withTransaction, withConnectionTransaction } from './transaction.js';
 export { assertIdentifier, quoteIdentifier } from './identifier.js';
 export { normalizeDisplayName, normalizeSchemaKey, resolveSchemaName } from './schema-key.js';
 export { YunCmsDatabaseError, normalizeDatabaseError, isRetryableDatabaseError } from './errors.js';
 export { withDatabaseRetry } from './retry.js';
+export {
+  MAINTENANCE_BYPASS_ENV,
+  maintenanceLockPath,
+  hashMaintenanceBypassToken,
+  assertMaintenanceStartupAllowed,
+} from './maintenance-state.js';
 export {
   createAccountability,
   createPublicAccountability,
@@ -12,22 +26,25 @@ export {
   requireAccountability,
 } from './accountability.js';
 export { createRequestContext } from './context.js';
-export {
-  createInitialAdmin,
-  findExistingAdmin,
-  findPublicRole,
-  ensurePublicRole,
-} from './setup.js';
-export { HookEmitter } from './hooks.js';
+export { createInitialAdmin, findExistingAdmin, findPublicRole, ensurePublicRole } from './setup.js';
+export { HookEmitter, HOOK_EVENTS } from './hooks.js';
 export { createJsonLogger, LEVELS as LOG_LEVELS } from './logger.js';
 export { deleteM2MJunction } from './m2m-lifecycle.js';
 export { createO2ORelation, deleteO2ORelation, o2oUniqueIndexName } from './o2o-relation.js';
 export {
   MAX_EXPAND_FIELDS,
+  MAX_RELATION_DEPTH,
   parseExpandInput,
   readManyWithRelations,
   readOneWithRelations,
 } from './relation-expansion.js';
+export {
+  assertLocalRedirectTarget,
+  createExternalAuthState,
+  hashExternalAuthState,
+  encryptExternalAuthSecret,
+  decryptExternalAuthSecret,
+} from './auth/external-state.js';
 export { SmtpMailer } from './mail/smtp-mailer.js';
 export { LocalStorageDriver, assertStorageKey } from './storage/local-storage-driver.js';
 export { S3StorageDriver } from './storage/s3-storage-driver.js';
@@ -37,6 +54,7 @@ export { createServiceRegistry } from './services/service-registry.js';
 export { createCoreServiceRegistry } from './services/core-services.js';
 export { AuthService } from './services/auth-service.js';
 export { AuthTokensService } from './services/auth-tokens-service.js';
+export { ExternalAuthService, AUTH_TRANSACTION_TTL_MS } from './services/external-auth-service.js';
 export { ApiTokensService } from './services/api-tokens-service.js';
 export { AuditService, redactAuditValue } from './services/audit-service.js';
 export { ItemsService } from './services/items-service.js';
@@ -63,20 +81,27 @@ export {
 } from './system-fields.js';
 export {
   assertActionOnlyPermissionPayload,
+  assertSystemPermissionPayload,
   assertSystemResourceAction,
   isPermissionManagedSystemResource,
   systemPermissionConfig,
 } from './system-permissions.js';
 export {
+  QUERY_LIMITS,
   parseItemsQuery,
+  queryCost,
+  assertQueryCost,
   compileSelectFields,
   compileSort,
   compileFilter,
+  compileSearch,
+  compileAggregate,
 } from './query.js';
 export { withAdvisoryLock } from './advisory-lock.js';
 export {
   ensureMigrationJournal,
   readAppliedMigrations,
+  readMigrationAttempts,
   validateMigration,
   applyMigrations,
   assertMigrationsApplied,

package/src/mail/smtp-mailer.js

@@ -13,6 +13,25 @@ function assertAddress(value, label) {
   return value.trim();
 }
 
+function normalizeMessage({ to, subject, text, html = undefined } = {}) {
+  const recipient = assertAddress(to, 'Recipient');
+  if (typeof subject !== 'string' || !subject.trim() || /[\r\n]/.test(subject)) {
+    throw mailError('INVALID_MAIL_MESSAGE', 'Mail subject is invalid');
+  }
+  if (typeof text !== 'string' || !text) {
+    throw mailError('INVALID_MAIL_MESSAGE', 'Mail text body is required');
+  }
+  if (html !== undefined && typeof html !== 'string') {
+    throw mailError('INVALID_MAIL_MESSAGE', 'Mail HTML body must be a string');
+  }
+  return {
+    to: recipient,
+    subject: subject.trim(),
+    text,
+    ...(html ? { html } : {}),
+  };
+}
+
 export class SmtpMailer {
   constructor({
     host,
@@ -22,9 +41,11 @@ export class SmtpMailer {
     password = null,
     from,
     transport = null,
+    emitter = null,
   } = {}) {
     if (!transport && (!host || typeof host !== 'string')) throw new Error('SMTP host is required');
     this.from = assertAddress(from, 'SMTP from address');
+    this.emitter = emitter;
     this.transport = transport ?? nodemailer.createTransport({
       host,
       port,
@@ -40,26 +61,49 @@ export class SmtpMailer {
     });
   }
 
+  setEmitter(emitter) {
+    this.emitter = emitter;
+    return this;
+  }
+
   async verify() {
     if (typeof this.transport.verify !== 'function') return true;
     return this.transport.verify();
   }
 
-  async send({ to, subject, text, html = undefined } = {}) {
-    const recipient = assertAddress(to, 'Recipient');
-    if (typeof subject !== 'string' || !subject.trim() || /[\r\n]/.test(subject)) {
-      throw mailError('INVALID_MAIL_MESSAGE', 'Mail subject is invalid');
-    }
-    if (typeof text !== 'string' || !text) {
-      throw mailError('INVALID_MAIL_MESSAGE', 'Mail text body is required');
+  async send(message = {}, context = {}) {
+    let normalized = normalizeMessage(message);
+    if (this.emitter) {
+      normalized = normalizeMessage(await this.emitter.filter('mail.send', normalized, {
+        accountability: context.accountability ?? null,
+        requestId: context.requestId ?? null,
+      }));
     }
 
-    return this.transport.sendMail({
-      from: this.from,
-      to: recipient,
-      subject: subject.trim(),
-      text,
-      ...(html ? { html } : {}),
-    });
+    try {
+      const result = await this.transport.sendMail({
+        from: this.from,
+        ...normalized,
+      });
+      await this.emitter?.action('mail.sent', {
+        to: normalized.to,
+        subject: normalized.subject,
+        messageId: result?.messageId ?? null,
+      }, {
+        accountability: context.accountability ?? null,
+        requestId: context.requestId ?? null,
+      });
+      return result;
+    } catch (error) {
+      await this.emitter?.action('mail.failed', {
+        to: normalized.to,
+        subject: normalized.subject,
+        code: error?.code ?? 'MAIL_DELIVERY_FAILED',
+      }, {
+        accountability: context.accountability ?? null,
+        requestId: context.requestId ?? null,
+      });
+      throw error;
+    }
   }
 }

package/src/maintenance-state.js

@@ -0,0 +1,89 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export const MAINTENANCE_BYPASS_ENV = 'YUNCMS_MAINTENANCE_BYPASS_TOKEN';
+
+function sha256(value) {
+  return createHash('sha256').update(String(value)).digest('hex');
+}
+
+export function canonicalProjectPath(cwd = process.cwd()) {
+  const absolute = resolve(cwd);
+  try {
+    return realpathSync.native ? realpathSync.native(absolute) : realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+
+export function maintenanceLockPath(cwd = process.cwd()) {
+  const projectKey = sha256(canonicalProjectPath(cwd)).slice(0, 32);
+  return join(tmpdir(), 'yuncms-update-locks', `${projectKey}.lock`);
+}
+
+export function hashMaintenanceBypassToken(token) {
+  if (typeof token !== 'string' || token.length < 32) {
+    const error = new Error('Maintenance bypass token must contain at least 32 characters');
+    error.code = 'MAINTENANCE_BYPASS_TOKEN_INVALID';
+    throw error;
+  }
+  return sha256(token);
+}
+
+function hashesEqual(left, right) {
+  if (typeof left !== 'string' || typeof right !== 'string') return false;
+  if (!/^[0-9a-f]{64}$/i.test(left) || !/^[0-9a-f]{64}$/i.test(right)) return false;
+  const leftBuffer = Buffer.from(left, 'hex');
+  const rightBuffer = Buffer.from(right, 'hex');
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+async function readMaintenanceState(path, readFileFn) {
+  let text;
+  try {
+    text = await readFileFn(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+
+  try {
+    const state = JSON.parse(text);
+    if (!state || typeof state !== 'object' || Array.isArray(state)) throw new Error('invalid state');
+    return state;
+  } catch (cause) {
+    const error = new Error(`YunCMS maintenance lock is unreadable or invalid: ${path}`);
+    error.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+    error.lockPath = path;
+    error.cause = cause;
+    throw error;
+  }
+}
+
+export async function assertMaintenanceStartupAllowed({
+  cwd = process.cwd(),
+  env = process.env,
+  readFileFn = readFile,
+} = {}) {
+  const path = maintenanceLockPath(cwd);
+  const state = await readMaintenanceState(path, readFileFn);
+  if (!state) return true;
+
+  const suppliedToken = env?.[MAINTENANCE_BYPASS_ENV];
+  if (typeof suppliedToken === 'string' && suppliedToken.length >= 32) {
+    const suppliedHash = sha256(suppliedToken);
+    if (hashesEqual(suppliedHash, state.bypassTokenHash)) return true;
+  }
+
+  const error = new Error(
+    `YunCMS maintenance is active for this project. Do not start the application until the maintenance operation finishes: ${path}`,
+  );
+  error.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+  error.lockPath = path;
+  error.startedAt = typeof state.startedAt === 'string' ? state.startedAt : null;
+  error.pid = Number.isInteger(state.pid) ? state.pid : null;
+  throw error;
+}

package/src/migrations/0011-role-permission-actions.js

@@ -0,0 +1,15 @@
+export const rolePermissionActionsMigration = {
+  id: '0011-role-permission-actions',
+  statements: [
+    `UPDATE yuncms_collections
+     SET metadata = JSON_SET(
+       COALESCE(metadata, JSON_OBJECT()),
+       '$.permissionManaged', TRUE,
+       '$.permissionMode', 'action-only',
+       '$.resource', 'roles',
+       '$.allowedActions', JSON_ARRAY('read', 'create', 'update', 'delete')
+     )
+     WHERE collection = 'yuncms_roles' AND \`system\` = 1`,
+    `UPDATE yuncms_schema_state SET version = version + 1 WHERE id = 1`,
+  ],
+};

package/src/migrations/0012-files-read-filters.js

@@ -0,0 +1,14 @@
+export const filesReadFiltersMigration = {
+  id: '0012-files-read-filters',
+  statements: [
+    `UPDATE yuncms_collections
+     SET metadata = JSON_SET(
+       COALESCE(metadata, JSON_OBJECT()),
+       '$.permissionMode',
+       'filter-read'
+     )
+     WHERE collection = 'yuncms_files'
+       AND \`system\` = 1`,
+    `UPDATE yuncms_schema_state SET version = version + 1 WHERE id = 1`,
+  ],
+};

package/src/migrations/0013-external-auth-foundation.js

@@ -0,0 +1,35 @@
+export const externalAuthFoundationMigration = {
+  id: '0013-external-auth-foundation',
+  statements: [
+    `CREATE TABLE IF NOT EXISTS yuncms_auth_identities (
+      id CHAR(36) NOT NULL PRIMARY KEY,
+      provider VARCHAR(64) NOT NULL,
+      subject VARCHAR(255) NOT NULL,
+      user CHAR(36) NOT NULL,
+      email VARCHAR(191) NULL,
+      profile JSON NULL,
+      last_login_at DATETIME(3) NULL,
+      created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+      updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+      UNIQUE KEY uq_yuncms_auth_identity_provider_subject (provider, subject),
+      KEY idx_yuncms_auth_identity_user (user),
+      CONSTRAINT fk_yuncms_auth_identity_user FOREIGN KEY (user)
+        REFERENCES yuncms_users (id) ON DELETE CASCADE
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
+
+    `CREATE TABLE IF NOT EXISTS yuncms_auth_transactions (
+      id CHAR(36) NOT NULL PRIMARY KEY,
+      provider VARCHAR(64) NOT NULL,
+      state_hash CHAR(64) NOT NULL,
+      secret_ciphertext TEXT NULL,
+      redirect_target VARCHAR(512) NULL,
+      metadata JSON NULL,
+      expires_at DATETIME(3) NOT NULL,
+      used_at DATETIME(3) NULL,
+      created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+      UNIQUE KEY uq_yuncms_auth_transaction_state (state_hash),
+      KEY idx_yuncms_auth_transaction_provider_expiry (provider, expires_at),
+      KEY idx_yuncms_auth_transaction_expiry (expires_at)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
+  ],
+};

package/src/migrations.js

@@ -1,4 +1,10 @@
 const JOURNAL_TABLE = 'yuncms_schema_migrations';
+const ATTEMPT_TABLE = 'yuncms_schema_migration_attempts';
+
+function truncateErrorMessage(value, maxLength = 1000) {
+  const message = String(value ?? 'Migration failed');
+  return message.length > maxLength ? message.slice(0, maxLength) : message;
+}
 
 export async function ensureMigrationJournal(database) {
   await database.query(`
@@ -7,6 +13,20 @@ export async function ensureMigrationJournal(database) {
       applied_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
+
+  await database.query(`
+    CREATE TABLE IF NOT EXISTS ${ATTEMPT_TABLE} (
+      migration_id VARCHAR(191) NOT NULL PRIMARY KEY,
+      status VARCHAR(16) NOT NULL,
+      statement_index INT UNSIGNED NOT NULL DEFAULT 0,
+      started_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+      finished_at DATETIME(3) NULL,
+      error_code VARCHAR(128) NULL,
+      error_message VARCHAR(1000) NULL,
+      CONSTRAINT chk_yuncms_schema_migration_attempt_status
+        CHECK (status IN ('applying', 'applied', 'failed'))
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
 }
 
 export async function readAppliedMigrations(database) {
@@ -14,6 +34,15 @@ export async function readAppliedMigrations(database) {
   return new Set(rows.map((row) => row.id));
 }
 
+export async function readMigrationAttempts(database) {
+  const [rows] = await database.query(
+    `SELECT migration_id, status, statement_index, started_at, finished_at, error_code, error_message
+     FROM ${ATTEMPT_TABLE}
+     ORDER BY started_at ASC, migration_id ASC`,
+  );
+  return rows;
+}
+
 export function validateMigration(migration) {
   if (!migration || typeof migration !== 'object') throw new Error('Migration must be an object');
   if (!migration.id || typeof migration.id !== 'string') throw new Error('Migration id is required');
@@ -26,23 +55,102 @@ export function validateMigration(migration) {
   return migration;
 }
 
+function migrationRecoveryError(attempts) {
+  const ids = attempts.map((attempt) => attempt.migration_id);
+  const error = new Error(
+    `Database contains an incomplete migration attempt and must be restored before retrying: ${ids.join(', ')}`,
+  );
+  error.code = 'DATABASE_MIGRATION_RECOVERY_REQUIRED';
+  error.migrationAttempts = attempts.map((attempt) => ({ ...attempt }));
+  return error;
+}
+
+async function assertNoIncompleteMigrationAttempts(database, applied, { allowMissingJournal = false } = {}) {
+  let attempts;
+  try {
+    attempts = await readMigrationAttempts(database);
+  } catch (error) {
+    if (allowMissingJournal && error?.code === 'ER_NO_SUCH_TABLE') return;
+    throw error;
+  }
+  const inconsistent = attempts.filter((attempt) => !applied.has(attempt.migration_id));
+  if (inconsistent.length > 0) throw migrationRecoveryError(inconsistent);
+}
+
+async function beginMigrationAttempt(database, migration) {
+  await database.query(
+    `INSERT INTO ${ATTEMPT_TABLE}
+       (migration_id, status, statement_index, started_at, finished_at, error_code, error_message)
+     VALUES (?, 'applying', 0, CURRENT_TIMESTAMP(3), NULL, NULL, NULL)`,
+    [migration.id],
+  );
+}
+
+async function advanceMigrationAttempt(database, migrationId, statementIndex) {
+  await database.query(
+    `UPDATE ${ATTEMPT_TABLE}
+     SET statement_index = ?
+     WHERE migration_id = ? AND status = 'applying'`,
+    [statementIndex, migrationId],
+  );
+}
+
+async function completeMigrationAttempt(database, migrationId) {
+  await database.query(
+    `UPDATE ${ATTEMPT_TABLE}
+     SET status = 'applied', finished_at = CURRENT_TIMESTAMP(3), error_code = NULL, error_message = NULL
+     WHERE migration_id = ?`,
+    [migrationId],
+  );
+}
+
+async function failMigrationAttempt(database, migrationId, error) {
+  await database.query(
+    `UPDATE ${ATTEMPT_TABLE}
+     SET status = 'failed', finished_at = CURRENT_TIMESTAMP(3), error_code = ?, error_message = ?
+     WHERE migration_id = ?`,
+    [
+      error?.code == null ? null : String(error.code).slice(0, 128),
+      truncateErrorMessage(error?.message),
+      migrationId,
+    ],
+  );
+}
+
 export async function applyMigrations(database, migrations) {
   if (!database) throw new Error('Database handle is required');
   if (!Array.isArray(migrations)) throw new Error('Migrations must be an array');
 
   await ensureMigrationJournal(database);
   const applied = await readAppliedMigrations(database);
+  await assertNoIncompleteMigrationAttempts(database, applied);
   const newlyApplied = [];
 
   for (const rawMigration of migrations) {
     const migration = validateMigration(rawMigration);
     if (applied.has(migration.id)) continue;
 
-    for (const statement of migration.statements) {
-      await database.query(statement);
+    await beginMigrationAttempt(database, migration);
+
+    try {
+      for (let index = 0; index < migration.statements.length; index += 1) {
+        await database.query(migration.statements[index]);
+        await advanceMigrationAttempt(database, migration.id, index + 1);
+      }
+
+      await database.query(`INSERT INTO ${JOURNAL_TABLE} (id) VALUES (?)`, [migration.id]);
+      await completeMigrationAttempt(database, migration.id);
+    } catch (error) {
+      try {
+        await failMigrationAttempt(database, migration.id, error);
+      } catch {
+        // The original migration error remains the source of truth. A stale 'applying'
+        // row still fails closed on the next bootstrap and requires restore/recovery.
+      }
+      error.migrationId ||= migration.id;
+      throw error;
     }
 
-    await database.query(`INSERT INTO ${JOURNAL_TABLE} (id) VALUES (?)`, [migration.id]);
     applied.add(migration.id);
     newlyApplied.push(migration.id);
   }
@@ -68,6 +176,8 @@ export async function assertMigrationsApplied(database, requiredMigrationIds) {
     throw error;
   }
 
+  await assertNoIncompleteMigrationAttempts(database, applied, { allowMissingJournal: true });
+
   const missing = requiredMigrationIds.filter((id) => !applied.has(id));
 
   if (missing.length > 0) {