@yunsoft/yuncms-core 0.1.25 → 0.1.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunsoft/yuncms-core",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Core services, schema, authentication, permissions and storage primitives for YunCMS.",
   "license": "MIT",
   "type": "module",

package/src/bootstrap.js

@@ -21,6 +21,7 @@ import { publicRegistrationSettingsMigration } from './migrations/0018-public-re
 import { publicRegistrationEmailVerificationMigration } from './migrations/0019-public-registration-email-verification.js';
 import { studioLocalesMigration } from './migrations/0020-studio-locales.js';
 import { aiAutomationsMigration } from './migrations/0021-ai-automations.js';
+import { utcAuthDeadlinesMigration } from './migrations/0022-utc-auth-deadlines.js';
 import { readSchemaVersion } from './schema-version.js';
 import { ensurePublicRole } from './setup.js';
 
@@ -46,6 +47,7 @@ export const CORE_MIGRATIONS = Object.freeze([
   publicRegistrationEmailVerificationMigration,
   studioLocalesMigration,
   aiAutomationsMigration,
+  utcAuthDeadlinesMigration,
 ]);
 
 export const REQUIRED_CORE_MIGRATION_IDS = Object.freeze(

package/src/database.js

@@ -3,12 +3,14 @@ import mysql from 'mysql2/promise';
 export function createDatabasePool(config) {
   if (!config) throw new Error('Database config is required');
 
-  return mysql.createPool({
+  const pool = mysql.createPool({
     host: config.host,
     port: config.port,
     database: config.database,
     user: config.user,
     password: config.password,
+    timezone: 'Z',
+    dateStrings: ['DATE'],
     waitForConnections: true,
     connectionLimit: config.connectionLimit ?? 10,
     queueLimit: 0,
@@ -19,6 +21,16 @@ export function createDatabasePool(config) {
     multipleStatements: false,
     ssl: config.ssl ? { minVersion: 'TLSv1.2' } : undefined,
   });
+
+  pool.on('connection', (connection) => {
+    connection.query("SET SESSION time_zone = '+00:00'", (err) => {
+      if (err) {
+        connection.destroy(err);
+      }
+    });
+  });
+
+  return pool;
 }
 
 export async function pingDatabase(pool) {

package/src/index.js

@@ -23,6 +23,9 @@ export { withDatabaseRetry } from './retry.js';
 export {
   MAINTENANCE_BYPASS_ENV,
   maintenanceLockPath,
+  legacyMaintenanceLockPath,
+  probeLegacyMaintenanceLock,
+  assertSecureUserParentDir,
   hashMaintenanceBypassToken,
   assertMaintenanceStartupAllowed,
 } from './maintenance-state.js';

package/src/maintenance-state.js

@@ -1,8 +1,8 @@
 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';
+import { lstat, readFile } from 'node:fs/promises';
+import { tmpdir, userInfo } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
 
 export const MAINTENANCE_BYPASS_ENV = 'YUNCMS_MAINTENANCE_BYPASS_TOKEN';
 
@@ -19,9 +19,48 @@ export function canonicalProjectPath(cwd = process.cwd()) {
   }
 }
 
-export function maintenanceLockPath(cwd = process.cwd()) {
+export function resolveUserIdentity({
+  userInfoFn = userInfo,
+  getuidFn = typeof process.getuid === 'function' ? () => process.getuid() : null,
+} = {}) {
+  if (typeof getuidFn === 'function') {
+    const rawUid = getuidFn();
+    if (Number.isSafeInteger(rawUid) && rawUid >= 0) {
+      return String(rawUid);
+    }
+    const err = new Error(`Operating system user identity is unavailable or invalid: ${rawUid}`);
+    err.code = 'OS_USER_IDENTITY_UNAVAILABLE';
+    throw err;
+  }
+  let info;
+  try {
+    info = userInfoFn();
+  } catch (error) {
+    const err = new Error('Operating system user identity is unavailable');
+    err.code = 'OS_USER_IDENTITY_UNAVAILABLE';
+    err.cause = error;
+    throw err;
+  }
+  const name = info?.username;
+  if (!name || typeof name !== 'string') {
+    const err = new Error('Operating system user identity is unavailable');
+    err.code = 'OS_USER_IDENTITY_UNAVAILABLE';
+    throw err;
+  }
+  return sha256(name).slice(0, 32);
+}
+
+export function maintenanceLockPath(cwd = process.cwd(), options = {}) {
+  const projectKey = sha256(canonicalProjectPath(cwd)).slice(0, 32);
+  const tempRoot = options?.tempRoot ?? tmpdir();
+  const identity = resolveUserIdentity(options);
+  return join(tempRoot, `yuncms-update-locks-${identity}`, `${projectKey}.lock`);
+}
+
+export function legacyMaintenanceLockPath(cwd = process.cwd(), options = {}) {
   const projectKey = sha256(canonicalProjectPath(cwd)).slice(0, 32);
-  return join(tmpdir(), 'yuncms-update-locks', `${projectKey}.lock`);
+  const tempRoot = options?.tempRoot ?? tmpdir();
+  return join(tempRoot, 'yuncms-update-locks', `${projectKey}.lock`);
 }
 
 export function hashMaintenanceBypassToken(token) {
@@ -41,6 +80,66 @@ function hashesEqual(left, right) {
   return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
 }
 
+export async function assertSecureUserParentDir(parentDir, {
+  lstatFn = lstat,
+  getuidFn = typeof process.getuid === 'function' ? () => process.getuid() : null,
+} = {}) {
+  let st;
+  try {
+    st = await lstatFn(parentDir);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return;
+    throw error;
+  }
+
+  const isSymlink = typeof st.isSymbolicLink === 'function' ? st.isSymbolicLink() : false;
+  if (isSymlink) {
+    const error = new Error(`YunCMS maintenance directory is an insecure symbolic link: ${parentDir}`);
+    error.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+    error.parentDir = parentDir;
+    throw error;
+  }
+
+  const isDir = typeof st.isDirectory === 'function' ? st.isDirectory() : false;
+  if (!isDir) {
+    const error = new Error(`YunCMS maintenance path is not a directory: ${parentDir}`);
+    error.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+    error.parentDir = parentDir;
+    throw error;
+  }
+
+  if (typeof getuidFn === 'function') {
+    const raw = getuidFn();
+    if (!Number.isSafeInteger(raw) || raw < 0) {
+      const error = new Error(`Operating system user identity is invalid: ${raw}`);
+      error.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+      error.parentDir = parentDir;
+      throw error;
+    }
+    const currentUid = raw;
+
+    if (typeof st.uid === 'number' && st.uid !== currentUid) {
+      const error = new Error(
+        `YunCMS maintenance directory is not owned by current user (owner UID ${st.uid}, current UID ${currentUid}): ${parentDir}`,
+      );
+      error.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+      error.parentDir = parentDir;
+      throw error;
+    }
+
+    const mode = typeof st.mode === 'number' ? st.mode : 0;
+    const isPrivate = (mode & 0o077) === 0;
+    if (!isPrivate) {
+      const error = new Error(
+        `YunCMS maintenance directory has insecure permissions (expected 0700): ${parentDir}`,
+      );
+      error.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+      error.parentDir = parentDir;
+      throw error;
+    }
+  }
+}
+
 async function readMaintenanceState(path, readFileFn) {
   let text;
   try {
@@ -63,27 +162,130 @@ async function readMaintenanceState(path, readFileFn) {
   }
 }
 
-export async function assertMaintenanceStartupAllowed({
+export async function probeLegacyMaintenanceLock({
   cwd = process.cwd(),
-  env = process.env,
+  tempRoot,
   readFileFn = readFile,
+  lstatFn = lstat,
+  getuidFn = typeof process.getuid === 'function' ? () => process.getuid() : null,
 } = {}) {
-  const path = maintenanceLockPath(cwd);
-  const state = await readMaintenanceState(path, readFileFn);
-  if (!state) return true;
+  const legacyPath = legacyMaintenanceLockPath(cwd, { tempRoot });
+  let state;
+  try {
+    state = await readMaintenanceState(legacyPath, readFileFn);
+  } catch (error) {
+    const causeCode = error?.cause?.code || error?.code;
+    if (causeCode === 'EACCES' || causeCode === 'EPERM') {
+      const legacyParent = dirname(legacyPath);
+      let st;
+      try {
+        st = await lstatFn(legacyParent);
+      } catch (statError) {
+        const failClosedError = new Error(
+          `YunCMS legacy maintenance directory is inaccessible: ${legacyParent}`,
+        );
+        failClosedError.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+        failClosedError.lockPath = legacyPath;
+        failClosedError.cause = error;
+        throw failClosedError;
+      }
+
+      let currentUid = null;
+      if (typeof getuidFn === 'function') {
+        const raw = getuidFn();
+        if (Number.isSafeInteger(raw) && raw >= 0) {
+          currentUid = raw;
+        } else {
+          const failClosedError = new Error(
+            `YunCMS legacy maintenance directory has invalid user identity: ${raw}`,
+          );
+          failClosedError.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+          failClosedError.lockPath = legacyPath;
+          throw failClosedError;
+        }
+      }
+
+      const isSymlink = typeof st.isSymbolicLink === 'function' ? st.isSymbolicLink() : false;
+      const isDir = typeof st.isDirectory === 'function' ? st.isDirectory() : false;
+      const parentUid = st.uid;
+      const mode = typeof st.mode === 'number' ? st.mode : 0;
+      const hasGroupOrWorldTraversal = (mode & 0o011) !== 0;
+      const isPrivateToOwner = (mode & 0o077) === 0;
+      const isForeignUid = typeof parentUid === 'number' && currentUid !== null && parentUid !== currentUid;
+
+      if (!isSymlink && isDir && isForeignUid && isPrivateToOwner && !hasGroupOrWorldTraversal) {
+        // Non-symlink private directory owned by another UID with no group/world traversal. Safe to ignore.
+        return null;
+      }
+
+      // Own, unknown owner, symlink, or insecure permissions fail-closed
+      const failClosedError = new Error(
+        `YunCMS legacy maintenance lock is inaccessible or insecure: ${legacyPath}`,
+      );
+      failClosedError.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+      failClosedError.lockPath = legacyPath;
+      failClosedError.cause = error;
+      throw failClosedError;
+    }
+    throw error;
+  }
+
+  if (!state) return null;
+  return { path: legacyPath, state };
+}
 
+function assertBypassTokenAllowed(state, lockPath, env) {
   const suppliedToken = env?.[MAINTENANCE_BYPASS_ENV];
   if (typeof suppliedToken === 'string' && suppliedToken.length >= 32) {
     const suppliedHash = sha256(suppliedToken);
-    if (hashesEqual(suppliedHash, state.bypassTokenHash)) return true;
+    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}`,
+    `YunCMS maintenance is active for this project. Do not start the application until the maintenance operation finishes: ${lockPath}`,
   );
   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;
+  error.lockPath = lockPath;
+  error.startedAt = typeof state?.startedAt === 'string' ? state.startedAt : null;
+  error.pid = Number.isInteger(state?.pid) ? state.pid : null;
   throw error;
 }
+
+export async function assertMaintenanceStartupAllowed({
+  cwd = process.cwd(),
+  env = process.env,
+  readFileFn = readFile,
+  lstatFn = lstat,
+  tempRoot,
+  getuidFn = typeof process.getuid === 'function' ? () => process.getuid() : null,
+  userInfoFn = userInfo,
+} = {}) {
+  const options = {
+    cwd,
+    env,
+    readFileFn,
+    lstatFn,
+    tempRoot,
+    getuidFn,
+    userInfoFn,
+  };
+
+  // 1. Check legacy lock path (0.1.26 compatibility)
+  const legacy = await probeLegacyMaintenanceLock(options);
+  if (legacy) {
+    assertBypassTokenAllowed(legacy.state, legacy.path, env);
+  }
+
+  // 2. Validate current per-user parent directory security if it exists
+  const currentPath = maintenanceLockPath(cwd, options);
+  const currentParent = dirname(currentPath);
+  await assertSecureUserParentDir(currentParent, { lstatFn, getuidFn });
+
+  // 3. Check current per-user lock
+  const currentState = await readMaintenanceState(currentPath, readFileFn);
+  if (currentState) {
+    assertBypassTokenAllowed(currentState, currentPath, env);
+  }
+
+  return true;
+}

package/src/migrations/0022-utc-auth-deadlines.js

@@ -0,0 +1,9 @@
+export const utcAuthDeadlinesMigration = Object.freeze({
+  id: '0022-utc-auth-deadlines',
+  statements: [
+    'DELETE FROM yuncms_sessions',
+    'DELETE FROM yuncms_auth_tokens',
+    'DELETE FROM yuncms_auth_transactions',
+    'DELETE FROM yuncms_api_tokens WHERE expires_at IS NOT NULL',
+  ],
+});

package/src/services/auth-service.js

@@ -144,7 +144,7 @@ export class AuthService extends BaseService {
        INNER JOIN yuncms_users u ON u.id = t.user
        LEFT JOIN yuncms_roles r ON r.id = u.role
        WHERE t.token_hash = ?
-         AND (t.expires_at IS NULL OR t.expires_at > CURRENT_TIMESTAMP(3))
+         AND (t.expires_at IS NULL OR t.expires_at > UTC_TIMESTAMP(3))
          AND u.status = 'active'
        LIMIT 1`,
       [hashToken(token)],
@@ -155,7 +155,7 @@ export class AuthService extends BaseService {
     await this.database.query(
       `UPDATE yuncms_api_tokens t
        INNER JOIN yuncms_users u ON u.id = t.user
-       SET t.last_used_at = CURRENT_TIMESTAMP(3), u.last_access = CURRENT_TIMESTAMP(3)
+       SET t.last_used_at = UTC_TIMESTAMP(3), u.last_access = UTC_TIMESTAMP(3)
        WHERE t.id = ?`,
       [row.api_token_id],
     );

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

@@ -116,7 +116,7 @@ export class AuthTokensService extends BaseService {
          WHERE token_hash = ?
            AND type = ?
            AND used_at IS NULL
-           AND expires_at > CURRENT_TIMESTAMP(3)
+           AND expires_at > UTC_TIMESTAMP(3)
          LIMIT 1
          FOR UPDATE`,
         [hashToken(token), TOKEN_TYPES.reset],
@@ -133,7 +133,7 @@ export class AuthTokensService extends BaseService {
       if (result.affectedRows !== 1) throw invalidActionToken();
 
       await connection.query(
-        'UPDATE yuncms_auth_tokens SET used_at = CURRENT_TIMESTAMP(3) WHERE id = ?',
+        'UPDATE yuncms_auth_tokens SET used_at = UTC_TIMESTAMP(3) WHERE id = ?',
         [actionToken.id],
       );
       await connection.query('DELETE FROM yuncms_sessions WHERE user = ?', [actionToken.user]);
@@ -203,7 +203,7 @@ export class AuthTokensService extends BaseService {
          WHERE token_hash = ?
            AND type = ?
            AND used_at IS NULL
-           AND expires_at > CURRENT_TIMESTAMP(3)
+           AND expires_at > UTC_TIMESTAMP(3)
          LIMIT 1
          FOR UPDATE`,
         [hashToken(token), TOKEN_TYPES.verify],
@@ -213,14 +213,14 @@ export class AuthTokensService extends BaseService {
 
       const [result] = await connection.query(
         `UPDATE yuncms_users
-         SET email_verified_at = COALESCE(email_verified_at, CURRENT_TIMESTAMP(3))
+         SET email_verified_at = COALESCE(email_verified_at, UTC_TIMESTAMP(3))
          WHERE id = ? AND status = 'active'`,
         [actionToken.user],
       );
       if (result.affectedRows !== 1) throw invalidActionToken();
 
       await connection.query(
-        'UPDATE yuncms_auth_tokens SET used_at = CURRENT_TIMESTAMP(3) WHERE id = ?',
+        'UPDATE yuncms_auth_tokens SET used_at = UTC_TIMESTAMP(3) WHERE id = ?',
         [actionToken.id],
       );
       await connection.query(

package/src/services/external-auth-service.js

@@ -123,7 +123,7 @@ export class ExternalAuthService extends BaseService {
       }
       const [result] = await connection.query(
         `UPDATE yuncms_auth_transactions
-         SET used_at = CURRENT_TIMESTAMP(3)
+         SET used_at = UTC_TIMESTAMP(3)
          WHERE id = ? AND used_at IS NULL`,
         [transaction.id],
       );
@@ -147,7 +147,7 @@ export class ExternalAuthService extends BaseService {
     if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 5000) throw new Error('Invalid auth transaction cleanup batch size');
     const [rows] = await this.database.query(
       `SELECT id FROM yuncms_auth_transactions
-       WHERE expires_at < CURRENT_TIMESTAMP(3) OR used_at IS NOT NULL
+       WHERE expires_at < UTC_TIMESTAMP(3) OR used_at IS NOT NULL
        ORDER BY created_at ASC
        LIMIT ?`,
       [batchSize],
@@ -226,7 +226,7 @@ export class ExternalAuthService extends BaseService {
           await connection.query(
             `INSERT INTO yuncms_users
              (id, email, password_hash, role, status, email_verified_at)
-             VALUES (?, ?, NULL, ?, 'active', CURRENT_TIMESTAMP(3))`,
+             VALUES (?, ?, NULL, ?, 'active', UTC_TIMESTAMP(3))`,
             [localUserId, normalizedEmail, role.id],
           );
         }
@@ -234,7 +234,7 @@ export class ExternalAuthService extends BaseService {
         await connection.query(
           `INSERT INTO yuncms_auth_identities
            (id, provider, subject, user, email, profile, last_login_at)
-           VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP(3))`,
+           VALUES (?, ?, ?, ?, ?, ?, UTC_TIMESTAMP(3))`,
           [randomUUID(), providerId, subjectId, localUserId, normalizedEmail, sanitizedProfile == null ? null : JSON.stringify(sanitizedProfile)],
         );
         return localUserId;
@@ -287,7 +287,7 @@ export class ExternalAuthService extends BaseService {
     } else {
       await this.database.query(
         `UPDATE yuncms_auth_identities
-         SET email = COALESCE(?, email), profile = COALESCE(?, profile), last_login_at = CURRENT_TIMESTAMP(3)
+         SET email = COALESCE(?, email), profile = COALESCE(?, profile), last_login_at = UTC_TIMESTAMP(3)
          WHERE id = ?`,
         [normalizedEmail, sanitizedProfile == null ? null : JSON.stringify(sanitizedProfile), user.identity_id],
       );

package/src/services/files-service.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { Readable } from 'node:stream';
 
 import { compileFilter } from '../query.js';
 import { BaseService } from './base-service.js';
@@ -73,6 +74,26 @@ function normalizeRow(row) {
   return row ? { ...row, metadata: decodeJson(row.metadata) } : null;
 }
 
+function normalizeModifiedAt(rawDate) {
+  if (!rawDate) return null;
+  const date = rawDate instanceof Date ? rawDate : new Date(rawDate);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+const STRONG_ETAG_PATTERN = /^"[!\x23-\x7e\x80-\xff]*"$/;
+
+function isValidStrongEtag(value) {
+  return typeof value === 'string' && STRONG_ETAG_PATTERN.test(value);
+}
+
+function resolveContentEtag(file, size, modifiedAt, providerEtag) {
+  if (isValidStrongEtag(providerEtag)) {
+    return providerEtag;
+  }
+  const mtimeMs = modifiedAt ? modifiedAt.getTime() : 0;
+  return `"${file.id}-${size.toString(16)}-${mtimeMs.toString(16)}"`;
+}
+
 export class FilesService extends BaseService {
   constructor(options = {}) {
     super(options);
@@ -231,6 +252,91 @@ export class FilesService extends BaseService {
     return { file, contents };
   }
 
+  async readContentInfo(id) {
+    const permission = await resolveSystemResourceAccess(this, 'read', 'yuncms_files');
+    const file = await this.#readOneAuthorized(id, permission);
+    if (!file) throw fileError('FILE_NOT_FOUND', `Unknown file: ${id}`);
+    const driver = this.storage.get(file.storage);
+    const stat = await driver.stat(file.filename_disk);
+    if (!stat) throw fileError('FILE_NOT_FOUND', `File content missing for file: ${id}`);
+    const size = Number(stat.size);
+    if (!Number.isSafeInteger(size) || size < 0) {
+      throw fileError('INVALID_FILE_SIZE', `Physical file size is invalid: ${stat.size}`);
+    }
+    const modifiedAt = normalizeModifiedAt(stat.modifiedAt ?? file.uploaded_at);
+    const etag = resolveContentEtag(file, size, modifiedAt, stat.etag);
+    return {
+      file,
+      size,
+      modifiedAt,
+      etag,
+    };
+  }
+
+  async readContentStream(id, { start, end } = {}) {
+    const permission = await resolveSystemResourceAccess(this, 'read', 'yuncms_files');
+    const file = await this.#readOneAuthorized(id, permission);
+    if (!file) throw fileError('FILE_NOT_FOUND', `Unknown file: ${id}`);
+    const driver = this.storage.get(file.storage);
+    const stat = await driver.stat(file.filename_disk);
+    if (!stat) throw fileError('FILE_NOT_FOUND', `File content missing for file: ${id}`);
+    const size = Number(stat.size);
+    if (!Number.isSafeInteger(size) || size < 0) {
+      throw fileError('INVALID_FILE_SIZE', `Physical file size is invalid: ${stat.size}`);
+    }
+
+    const rangeStart = typeof start === 'number' ? start : 0;
+    if (start !== undefined) {
+      if (!Number.isSafeInteger(start) || start < 0) {
+        throw fileError('INVALID_RANGE', 'Range start must be a non-negative integer');
+      }
+      if (size === 0 || start >= size) {
+        throw fileError('INVALID_RANGE', 'Range start is out of bounds');
+      }
+    }
+
+    if (end !== undefined) {
+      if (!Number.isSafeInteger(end) || end < rangeStart) {
+        throw fileError('INVALID_RANGE', 'Range end must be greater than or equal to start');
+      }
+      if (size === 0 || end >= size) {
+        throw fileError('INVALID_RANGE', 'Range end is out of bounds');
+      }
+    }
+
+    let stream;
+    if (typeof driver.getStream === 'function') {
+      stream = await driver.getStream(file.filename_disk, { start, end });
+      if (!stream) throw fileError('FILE_NOT_FOUND', `File content missing for file: ${id}`);
+      if (!(stream instanceof Readable)) {
+        throw fileError('INVALID_STREAM', 'Storage getStream must return a Node Readable stream');
+      }
+    } else {
+      const raw = await driver.get(file.filename_disk);
+      if (!Buffer.isBuffer(raw) && !(raw instanceof Uint8Array)) {
+        throw fileError('INVALID_FILE_CONTENT', 'Storage get must return Buffer or Uint8Array');
+      }
+      const buffer = Buffer.isBuffer(raw)
+        ? raw
+        : Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength);
+      const slice = typeof end === 'number'
+        ? buffer.subarray(rangeStart, end + 1)
+        : (typeof start === 'number' ? buffer.subarray(start) : buffer);
+      stream = Readable.from([slice]);
+    }
+
+    const modifiedAt = normalizeModifiedAt(stat.modifiedAt ?? file.uploaded_at);
+    const etag = resolveContentEtag(file, size, modifiedAt, stat.etag);
+
+    return {
+      file,
+      stream,
+      size,
+      modifiedAt,
+      etag,
+    };
+  }
+
   async updateOne(id, patch = {}) {
     await resolveSystemResourceAccess(this, 'update', 'yuncms_files');
     if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {

package/src/services/items-service.js

@@ -231,10 +231,10 @@ export class ItemsService extends BaseService {
     return combineCompiledFilters(permissionSql, userSql, searchSql);
   }
 
-  async normalizeReadQuery(rawQuery) {
+  async normalizeReadQuery(rawQuery, context = {}) {
     const parsed = parseItemsQuery(rawQuery);
     const filtered = this.emitter
-      ? await this.emitter.filter('items.query', parsed, this.hookContext({ operation: 'read' }))
+      ? await this.emitter.filter('items.query', parsed, this.hookContext({ ...context, operation: 'read' }))
       : parsed;
     const query = parseItemsQuery(filtered);
     assertQueryCost(query);
@@ -298,10 +298,65 @@ export class ItemsService extends BaseService {
     const requestedFields = normalizeFields(query.fields);
     const selected = compileSelectFields(requestedFields, accessSchema);
     const sortSql = compileSort(query.sort, accessSchema);
-    const [rows] = await this.database.query(
-      `SELECT ${selected.sql} FROM ${table}${filter.sql}${sortSql} LIMIT ? OFFSET ?`,
-      [...filter.params, query.limit, query.offset],
-    );
+    const hasExplicitSort = Boolean(query.sort && query.sort.length > 0);
+    const hasLargeField = selected.fields.some((fieldName) => {
+      const fieldType = accessSchema.fields[fieldName]?.type ?? schema.fields[fieldName]?.type;
+      return fieldType === 'json' || fieldType === 'text';
+    });
+
+    let rows;
+
+    if (hasExplicitSort && hasLargeField) {
+      const primaryKey = schema.primary_key;
+      const pkSql = quoteIdentifier(primaryKey, 'primary key');
+      const [idRows] = await this.database.query(
+        `SELECT ${pkSql} FROM ${table}${filter.sql}${sortSql} LIMIT ? OFFSET ?`,
+        [...filter.params, query.limit, query.offset],
+      );
+
+      const pageIds = idRows.map((row) => row[primaryKey]).filter((id) => id != null);
+      rows = [];
+
+      if (pageIds.length > 0) {
+        const primaryKeyRequestedAndAllowed = selected.fields.includes(primaryKey);
+        const materializationSql = primaryKeyRequestedAndAllowed
+          ? selected.sql
+          : `${selected.sql}, ${pkSql}`;
+        const idFilter = {
+          sql: ` WHERE ${pkSql} IN (${pageIds.map(() => '?').join(', ')})`,
+          params: pageIds,
+        };
+        const secondFilter = combineCompiledFilters(filter, idFilter);
+        const [materializedRows] = await this.database.query(
+          `SELECT ${materializationSql} FROM ${table}${secondFilter.sql}`,
+          secondFilter.params,
+        );
+
+        const rowMap = new Map();
+        for (const row of materializedRows) {
+          rowMap.set(row[primaryKey], row);
+        }
+
+        for (const id of pageIds) {
+          const row = rowMap.get(id);
+          if (row) {
+            if (!primaryKeyRequestedAndAllowed) {
+              const { [primaryKey]: _ignored, ...rest } = row;
+              rows.push(rest);
+            } else {
+              rows.push(row);
+            }
+          }
+        }
+      }
+    } else {
+      const [resultRows] = await this.database.query(
+        `SELECT ${selected.sql} FROM ${table}${filter.sql}${sortSql} LIMIT ? OFFSET ?`,
+        [...filter.params, query.limit, query.offset],
+      );
+      rows = resultRows;
+    }
+
     const [countRows] = await this.database.query(
       `SELECT COUNT(*) AS total_count FROM ${table}${filter.sql}`,
       filter.params,
@@ -363,14 +418,18 @@ export class ItemsService extends BaseService {
 
   async readOne(id, { fields = null } = {}) {
     const schema = await this.getCollectionSchema();
+    const query = await this.normalizeReadQuery({ fields, limit: 1 }, { single: true, key: id });
+    if (query.aggregate) {
+      throw serviceError('INVALID_QUERY', 'Single-item reads do not support aggregate queries', 'aggregate');
+    }
     const permission = await this.resolvePermission('read');
     const accessSchema = schemaForFields(schema, permission.fields);
-    const selected = compileSelectFields(normalizeFields(fields), accessSchema);
+    const selected = compileSelectFields(query.fields, accessSchema);
     const table = quoteIdentifier(this.collection, 'collection name');
     const primaryKey = schema.primary_key;
     const dynamicVariables = this.dynamicVariables();
     const filter = combineCompiledFilters(
-      compileFilter(permission.filter, schema, { dynamicVariables }),
+      this.compileActionFilters(query.filter, permission.filter, accessSchema, schema, query.search, dynamicVariables),
       compileFilter({ [primaryKey]: { _eq: id } }, schema),
     );
     const [rows] = await this.database.query(
@@ -378,7 +437,7 @@ export class ItemsService extends BaseService {
       filter.params,
     );
     const record = rows[0] ?? null;
-    if (record) await this.emitReadAction({ fields: normalizeFields(fields) }, [record], schema, { single: true });
+    if (record) await this.emitReadAction(query, [record], schema, { single: true });
     return record;
   }
 

package/src/services/roles-service.js

@@ -1,5 +1,10 @@
 import { randomUUID } from 'node:crypto';
 
+import {
+  buildSystemListQuery,
+  ROLE_SAFE_SELECT_COLUMNS,
+  ROLE_SYSTEM_SEARCH_SCHEMA,
+} from '../system-list-query.js';
 import { BaseService } from './base-service.js';
 import { resolveSystemResourceAccess } from './system-resource-access.js';
 
@@ -48,13 +53,15 @@ export class RolesService extends BaseService {
     return rows[0] ?? null;
   }
 
-  async readMany() {
+  async readMany(query = {}) {
     await resolveSystemResourceAccess(this, 'read', 'yuncms_roles');
-    const [rows] = await this.database.query(
-      `SELECT id, name, description, admin, public, created_at, updated_at
-       FROM yuncms_roles
-       ORDER BY name ASC`,
-    );
+    const { sql, params } = buildSystemListQuery(query, {
+      table: 'yuncms_roles',
+      columns: ROLE_SAFE_SELECT_COLUMNS,
+      orderBy: 'name ASC, id ASC',
+      searchSchema: ROLE_SYSTEM_SEARCH_SCHEMA,
+    });
+    const [rows] = await this.database.query(sql, params);
     return rows;
   }
 

package/src/services/sessions-service.js

@@ -77,8 +77,8 @@ export class SessionsService extends BaseService {
        INNER JOIN yuncms_users u ON u.id = s.user
        LEFT JOIN yuncms_roles r ON r.id = u.role
        WHERE s.access_token_hash = ?
-         AND s.access_expires_at > CURRENT_TIMESTAMP(3)
-         AND s.expires_at > CURRENT_TIMESTAMP(3)
+         AND s.access_expires_at > UTC_TIMESTAMP(3)
+         AND s.expires_at > UTC_TIMESTAMP(3)
          AND u.status = 'active'
        LIMIT 1`,
       [hash],
@@ -89,7 +89,7 @@ export class SessionsService extends BaseService {
     await this.database.query(
       `UPDATE yuncms_sessions s
        INNER JOIN yuncms_users u ON u.id = s.user
-       SET s.last_used_at = CURRENT_TIMESTAMP(3), u.last_access = CURRENT_TIMESTAMP(3)
+       SET s.last_used_at = UTC_TIMESTAMP(3), u.last_access = UTC_TIMESTAMP(3)
        WHERE s.id = ?`,
       [row.session_id],
     );
@@ -111,7 +111,7 @@ export class SessionsService extends BaseService {
        INNER JOIN yuncms_users u ON u.id = s.user
        LEFT JOIN yuncms_roles r ON r.id = u.role
        WHERE s.token_hash = ?
-         AND s.expires_at > CURRENT_TIMESTAMP(3)
+         AND s.expires_at > UTC_TIMESTAMP(3)
          AND u.status = 'active'
        LIMIT 1`,
       [oldHash],
@@ -126,7 +126,7 @@ export class SessionsService extends BaseService {
     const [result] = await this.database.query(
       `UPDATE yuncms_sessions
        SET token_hash = ?, access_token_hash = ?, access_expires_at = ?, expires_at = ?,
-           last_used_at = CURRENT_TIMESTAMP(3)
+           last_used_at = UTC_TIMESTAMP(3)
        WHERE id = ? AND token_hash = ?`,
       [
         refresh.hash,

package/src/services/singleton-services.js

@@ -29,6 +29,7 @@ export class SingletonItemsService extends ItemsService {
   async createOne(payload = {}) {
     const schema = await this.getCollectionSchema();
     if (!schema.singleton) return super.createOne(payload);
+    await this.resolvePermission('create');
     return withAdvisoryLock(
       this.database,
       singletonLockName(this.collection),
@@ -43,6 +44,7 @@ export class SingletonItemsService extends ItemsService {
   async createMany(payloads = []) {
     const schema = await this.getCollectionSchema();
     if (!schema.singleton) return super.createMany(payloads);
+    await this.resolvePermission('create');
     if (!Array.isArray(payloads) || payloads.length !== 1) {
       throw singletonError('SINGLETON_BULK_CREATE_FORBIDDEN', 'Singleton collections accept exactly one create payload');
     }

package/src/services/users-service.js

@@ -1,6 +1,11 @@
 import { randomUUID } from 'node:crypto';
 
 import { hashPassword } from '../auth/password.js';
+import {
+  buildSystemListQuery,
+  USER_SAFE_SELECT_COLUMNS,
+  USER_SYSTEM_SEARCH_SCHEMA,
+} from '../system-list-query.js';
 import { withTransaction } from '../transaction.js';
 import { BaseService } from './base-service.js';
 import { resolveSystemResourceAccess } from './system-resource-access.js';
@@ -118,13 +123,15 @@ export class UsersService extends BaseService {
     return rows[0] ?? null;
   }
 
-  async readMany() {
+  async readMany(query = {}) {
     await resolveSystemResourceAccess(this, 'read', 'yuncms_users');
-    const [rows] = await this.database.query(
-      `SELECT id, email, role, status, email_verified_at, last_access, created_at, updated_at
-       FROM yuncms_users
-       ORDER BY email ASC`,
-    );
+    const { sql, params } = buildSystemListQuery(query, {
+      table: 'yuncms_users',
+      columns: USER_SAFE_SELECT_COLUMNS,
+      orderBy: 'email ASC, id ASC',
+      searchSchema: USER_SYSTEM_SEARCH_SCHEMA,
+    });
+    const [rows] = await this.database.query(sql, params);
     return rows;
   }
 

package/src/storage/local-storage-driver.js

@@ -1,3 +1,4 @@
+import { createReadStream } from 'node:fs';
 import { mkdir, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises';
 import { isAbsolute, relative, resolve } from 'node:path';
 
@@ -46,6 +47,17 @@ export class LocalStorageDriver {
     return readFile(this.pathFor(key));
   }
 
+  async getStream(key, { start, end } = {}) {
+    const path = this.pathFor(key);
+    const options = { highWaterMark: 64 * 1024 };
+    if (typeof start === 'number') options.start = start;
+    if (typeof end === 'number') {
+      options.end = end;
+      if (typeof start !== 'number') options.start = 0;
+    }
+    return createReadStream(path, options);
+  }
+
   async stat(key) {
     try {
       const info = await stat(this.pathFor(key));

package/src/storage/s3-storage-driver.js

@@ -76,6 +76,22 @@ export class S3StorageDriver {
     return bodyToBuffer(response.Body);
   }
 
+  async getStream(key, { start, end } = {}) {
+    const safeKey = assertStorageKey(key);
+    const commandInput = {
+      Bucket: this.bucket,
+      Key: safeKey,
+    };
+    if (typeof end === 'number') {
+      const rangeStart = typeof start === 'number' ? start : 0;
+      commandInput.Range = `bytes=${rangeStart}-${end}`;
+    } else if (typeof start === 'number') {
+      commandInput.Range = `bytes=${start}-`;
+    }
+    const response = await this.client.send(new GetObjectCommand(commandInput));
+    return response.Body;
+  }
+
   async stat(key) {
     const safeKey = assertStorageKey(key);
     try {

package/src/storage/storage-registry.js

@@ -4,6 +4,9 @@ function assertDriver(name, driver) {
       throw new Error(`Storage driver ${name} must implement ${method}()`);
     }
   }
+  if (driver.getStream != null && typeof driver.getStream !== 'function') {
+    throw new Error(`Storage driver ${name} getStream must be a function when provided`);
+  }
   return driver;
 }
 

package/src/system-list-query.js

@@ -0,0 +1,124 @@
+import { assertIdentifier } from './identifier.js';
+import { compileSearch, parseItemsQuery, QUERY_LIMITS } from './query.js';
+
+export const SYSTEM_LIST_LIMITS = Object.freeze({
+  defaultLimit: QUERY_LIMITS.defaultLimit,
+  minLimit: 1,
+  maxLimit: QUERY_LIMITS.maxLimit,
+  defaultOffset: 0,
+  minOffset: 0,
+  maxOffset: QUERY_LIMITS.maxOffset,
+  maxSearchLength: QUERY_LIMITS.maxSearchLength,
+});
+
+const ALLOWED_QUERY_KEYS = new Set(['limit', 'offset', 'search']);
+
+export const USER_SAFE_SELECT_COLUMNS = Object.freeze([
+  'id',
+  'email',
+  'role',
+  'status',
+  'email_verified_at',
+  'last_access',
+  'created_at',
+  'updated_at',
+]);
+
+export const ROLE_SAFE_SELECT_COLUMNS = Object.freeze([
+  'id',
+  'name',
+  'description',
+  'admin',
+  'public',
+  'created_at',
+  'updated_at',
+]);
+
+export const USER_SYSTEM_SEARCH_SCHEMA = Object.freeze({
+  fields: {
+    email: { field: 'email', type: 'string' },
+  },
+});
+
+export const ROLE_SYSTEM_SEARCH_SCHEMA = Object.freeze({
+  fields: {
+    name: { field: 'name', type: 'string' },
+    description: { field: 'description', type: 'string' },
+  },
+});
+
+function queryError(message, path = null) {
+  const error = new Error(message);
+  error.code = 'INVALID_QUERY';
+  if (path) error.path = path;
+  return error;
+}
+
+export function parseSystemListQuery(raw = {}) {
+  if (raw == null) {
+    return Object.freeze({
+      isBounded: false,
+      limit: null,
+      offset: null,
+      search: null,
+    });
+  }
+
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw queryError('Query must be an object');
+  }
+
+  const keys = Object.keys(raw);
+  if (keys.length === 0) {
+    return Object.freeze({
+      isBounded: false,
+      limit: null,
+      offset: null,
+      search: null,
+    });
+  }
+
+  for (const key of keys) {
+    if (!ALLOWED_QUERY_KEYS.has(key)) {
+      throw queryError(`Unknown query parameter: ${key}`, key);
+    }
+  }
+
+  if (raw.search !== undefined && raw.search !== null && raw.search !== '') {
+    if (typeof raw.search !== 'string') {
+      throw queryError('search must be a string', 'search');
+    }
+  }
+
+  const parsed = parseItemsQuery(raw);
+
+  return Object.freeze({
+    isBounded: true,
+    limit: parsed.limit,
+    offset: parsed.offset,
+    search: parsed.search,
+  });
+}
+
+export function buildSystemListQuery(rawQuery, { table, columns, orderBy, searchSchema }) {
+  const parsed = parseSystemListQuery(rawQuery);
+  const validatedTable = assertIdentifier(table, 'table');
+  const validatedColumns = columns.map((col) => assertIdentifier(col, 'column')).join(', ');
+
+  if (!parsed.isBounded) {
+    return {
+      parsed,
+      sql: `SELECT ${validatedColumns}\nFROM ${validatedTable}\nORDER BY ${orderBy}`,
+      params: [],
+    };
+  }
+
+  const searchResult = compileSearch(parsed.search, searchSchema);
+  const whereSql = searchResult.sql ? `\n${searchResult.sql.trim()}` : '';
+
+  return {
+    parsed,
+    sql: `SELECT ${validatedColumns}\nFROM ${validatedTable}${whereSql}\nORDER BY ${orderBy}\nLIMIT ? OFFSET ?`,
+    params: [...searchResult.params, parsed.limit, parsed.offset],
+  };
+}