@yunsoft/yuncms-core 0.1.5 → 0.1.6

package/package.json

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

package/src/auth/external-state.js

@@ -0,0 +1,76 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes,
+  timingSafeEqual,
+} from 'node:crypto';
+
+function authStateError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function stateKey(secret) {
+  if (typeof secret !== 'string' || secret.length < 32) {
+    throw authStateError('INVALID_AUTH_PROVIDER_CONFIG', 'AUTH_STATE_SECRET must contain at least 32 characters');
+  }
+  return createHash('sha256').update(secret, 'utf8').digest();
+}
+
+export function createExternalAuthState(bytes = 32) {
+  if (!Number.isInteger(bytes) || bytes < 24 || bytes > 64) throw new Error('External auth state bytes must be between 24 and 64');
+  return randomBytes(bytes).toString('base64url');
+}
+
+export function hashExternalAuthState(value) {
+  if (typeof value !== 'string' || value.length < 16 || value.length > 512) {
+    throw authStateError('INVALID_AUTH_TRANSACTION', 'External auth state is invalid');
+  }
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+export function constantTimeStateEqual(left, right) {
+  const a = Buffer.from(hashExternalAuthState(left), 'hex');
+  const b = Buffer.from(hashExternalAuthState(right), 'hex');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+export function encryptExternalAuthSecret(secret, value) {
+  if (value == null) return null;
+  const key = stateKey(secret);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const plaintext = Buffer.from(JSON.stringify(value), 'utf8');
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return `v1.${iv.toString('base64url')}.${tag.toString('base64url')}.${ciphertext.toString('base64url')}`;
+}
+
+export function decryptExternalAuthSecret(secret, value) {
+  if (value == null) return null;
+  const parts = String(value).split('.');
+  if (parts.length !== 4 || parts[0] !== 'v1') throw authStateError('INVALID_AUTH_TRANSACTION', 'External auth transaction secret is invalid');
+  try {
+    const key = stateKey(secret);
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(parts[1], 'base64url'));
+    decipher.setAuthTag(Buffer.from(parts[2], 'base64url'));
+    const plaintext = Buffer.concat([
+      decipher.update(Buffer.from(parts[3], 'base64url')),
+      decipher.final(),
+    ]).toString('utf8');
+    return JSON.parse(plaintext);
+  } catch (error) {
+    throw authStateError('INVALID_AUTH_TRANSACTION', `External auth transaction secret could not be verified: ${error?.code ?? 'decrypt_failed'}`);
+  }
+}
+
+export function assertLocalRedirectTarget(value, fallback = '/') {
+  if (value == null || value === '') return fallback;
+  const target = String(value);
+  if (!target.startsWith('/') || target.startsWith('//') || target.includes('\\') || /[\r\n\0]/.test(target) || target.length > 512) {
+    throw authStateError('INVALID_REDIRECT_TARGET', 'External auth redirect target must be a local path');
+  }
+  return target;
+}

package/src/bootstrap.js

@@ -12,6 +12,7 @@ import { schemaDisplayNamesMigration } from './migrations/0009-schema-display-na
 import { studioFaviconFileMigration } from './migrations/0010-studio-favicon-file.js';
 import { rolePermissionActionsMigration } from './migrations/0011-role-permission-actions.js';
 import { filesReadFiltersMigration } from './migrations/0012-files-read-filters.js';
+import { externalAuthFoundationMigration } from './migrations/0013-external-auth-foundation.js';
 import { readSchemaVersion } from './schema-version.js';
 import { ensurePublicRole } from './setup.js';
 
@@ -28,6 +29,7 @@ export const CORE_MIGRATIONS = Object.freeze([
   studioFaviconFileMigration,
   rolePermissionActionsMigration,
   filesReadFiltersMigration,
+  externalAuthFoundationMigration,
 ]);
 
 export const REQUIRED_CORE_MIGRATION_IDS = Object.freeze(

package/src/config.js

@@ -4,12 +4,10 @@ export const DEFAULT_SERVER_PORT = 3008;
 
 function readInteger(value, fallback, name, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) {
   if (value === undefined || value === '') return fallback;
-
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
     throw new Error(`${name} must be an integer between ${min} and ${max}`);
   }
-
   return parsed;
 }
 
@@ -24,14 +22,72 @@ function readString(value, fallback = '') {
   return value === undefined ? fallback : String(value);
 }
 
-function readCacheStore(value) {
-  const store = readString(value, 'memory').trim().toLowerCase();
-  if (store !== 'memory') {
-    throw new Error(`CACHE_STORE must be memory until a shared-store adapter is configured, received: ${store}`);
+function readStore(value, fallback, name) {
+  const store = readString(value, fallback).trim().toLowerCase();
+  if (!['memory', 'redis'].includes(store)) {
+    throw new Error(`${name} must be memory or redis, received: ${store}`);
   }
   return store;
 }
 
+function readFailureMode(value, fallback = 'best-effort') {
+  const mode = readString(value, fallback).trim().toLowerCase();
+  if (!['best-effort', 'required'].includes(mode)) {
+    throw new Error(`RATE_LIMIT_FAILURE_MODE must be best-effort or required, received: ${mode}`);
+  }
+  return mode;
+}
+
+function readOriginList(value, fallback) {
+  const entries = readString(value, '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const source = entries.length > 0 ? entries : [fallback];
+  return [...new Set(source.map((entry) => {
+    let url;
+    try {
+      url = new URL(entry);
+    } catch {
+      throw new Error(`MCP_ALLOWED_ORIGINS contains an invalid URL: ${entry}`);
+    }
+    if (!['http:', 'https:'].includes(url.protocol)) {
+      throw new Error(`MCP_ALLOWED_ORIGINS must use http or https: ${entry}`);
+    }
+    return url.origin;
+  }))];
+}
+
+function readHostList(value, fallbackOrigin) {
+  let fallbackHost;
+  try {
+    fallbackHost = new URL(fallbackOrigin).host.toLowerCase();
+  } catch {
+    throw new Error(`Cannot derive MCP host from STUDIO_ORIGIN: ${fallbackOrigin}`);
+  }
+  const entries = readString(value, '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const source = entries.length > 0 ? entries : [fallbackHost];
+
+  return [...new Set(source.map((entry) => {
+    if (/[:][/][/]|[\\/?#@\s\0]/.test(entry)) {
+      throw new Error(`MCP_ALLOWED_HOSTS contains an invalid host: ${entry}`);
+    }
+    let url;
+    try {
+      url = new URL(`http://${entry}`);
+    } catch {
+      throw new Error(`MCP_ALLOWED_HOSTS contains an invalid host: ${entry}`);
+    }
+    if (url.username || url.password || url.pathname !== '/' || url.search || url.hash || !url.host) {
+      throw new Error(`MCP_ALLOWED_HOSTS contains an invalid host: ${entry}`);
+    }
+    return url.host.toLowerCase();
+  }))];
+}
+
 export function loadEnvFileIfPresent(path = '.env') {
   try {
     loadEnvFile(path);
@@ -45,6 +101,13 @@ export function loadEnvFileIfPresent(path = '.env') {
 export function loadConfig(env = process.env) {
   const serverPort = readInteger(env.PORT, DEFAULT_SERVER_PORT, 'PORT', { min: 1, max: 65535 });
   const studioOrigin = readString(env.STUDIO_ORIGIN, `http://localhost:${serverPort}`);
+  const cacheStore = readStore(env.CACHE_STORE, 'memory', 'CACHE_STORE');
+  const apiRateLimitStore = readStore(env.API_RATE_LIMIT_STORE, 'memory', 'API_RATE_LIMIT_STORE');
+  const authRateLimitStore = readStore(env.AUTH_RATE_LIMIT_STORE, apiRateLimitStore, 'AUTH_RATE_LIMIT_STORE');
+  const redisUrl = readString(env.REDIS_URL, '') || null;
+  if ([cacheStore, apiRateLimitStore, authRateLimitStore].includes('redis') && !redisUrl) {
+    throw new Error('REDIS_URL is required when any cache or rate-limit store is redis');
+  }
 
   return {
     server: {
@@ -54,49 +117,41 @@ export function loadConfig(env = process.env) {
       trustProxyHops: readInteger(env.TRUST_PROXY_HOPS, 0, 'TRUST_PROXY_HOPS', { min: 0, max: 10 }),
       rateLimit: {
         enabled: readBoolean(env.API_RATE_LIMIT_ENABLED, true),
-        windowMs: readInteger(env.API_RATE_LIMIT_WINDOW_MS, 60_000, 'API_RATE_LIMIT_WINDOW_MS', {
-          min: 1000,
-          max: 24 * 60 * 60 * 1000,
-        }),
-        max: readInteger(env.API_RATE_LIMIT_MAX, 300, 'API_RATE_LIMIT_MAX', {
-          min: 1,
-          max: 1_000_000,
-        }),
-        maxBuckets: readInteger(env.API_RATE_LIMIT_MAX_BUCKETS, 10_000, 'API_RATE_LIMIT_MAX_BUCKETS', {
-          min: 1,
-          max: 1_000_000,
-        }),
+        store: apiRateLimitStore,
+        failureMode: readFailureMode(env.RATE_LIMIT_FAILURE_MODE),
+        windowMs: readInteger(env.API_RATE_LIMIT_WINDOW_MS, 60_000, 'API_RATE_LIMIT_WINDOW_MS', { min: 1000, max: 24 * 60 * 60 * 1000 }),
+        max: readInteger(env.API_RATE_LIMIT_MAX, 300, 'API_RATE_LIMIT_MAX', { min: 1, max: 1_000_000 }),
+        maxBuckets: readInteger(env.API_RATE_LIMIT_MAX_BUCKETS, 10_000, 'API_RATE_LIMIT_MAX_BUCKETS', { min: 1, max: 1_000_000 }),
       },
       pressure: {
         enabled: readBoolean(env.PRESSURE_LIMIT_ENABLED, true),
-        maxConcurrent: readInteger(env.PRESSURE_MAX_CONCURRENT, 250, 'PRESSURE_MAX_CONCURRENT', {
-          min: 1,
-          max: 100_000,
-        }),
-        maxHeapPercent: readInteger(env.PRESSURE_MAX_HEAP_PERCENT, 95, 'PRESSURE_MAX_HEAP_PERCENT', {
-          min: 1,
-          max: 100,
-        }),
-        retryAfterSeconds: readInteger(env.PRESSURE_RETRY_AFTER_SECONDS, 1, 'PRESSURE_RETRY_AFTER_SECONDS', {
-          min: 1,
-          max: 3600,
-        }),
+        maxConcurrent: readInteger(env.PRESSURE_MAX_CONCURRENT, 250, 'PRESSURE_MAX_CONCURRENT', { min: 1, max: 100_000 }),
+        maxHeapPercent: readInteger(env.PRESSURE_MAX_HEAP_PERCENT, 95, 'PRESSURE_MAX_HEAP_PERCENT', { min: 1, max: 100 }),
+        retryAfterSeconds: readInteger(env.PRESSURE_RETRY_AFTER_SECONDS, 1, 'PRESSURE_RETRY_AFTER_SECONDS', { min: 1, max: 3600 }),
       },
     },
-    logging: {
-      level: readString(env.LOG_LEVEL, 'info'),
+    logging: { level: readString(env.LOG_LEVEL, 'info') },
+    mcp: {
+      enabled: readBoolean(env.MCP_ENABLED, false),
+      writesEnabled: readBoolean(env.MCP_WRITES_ENABLED, false),
+      requireAuthentication: readBoolean(env.MCP_REQUIRE_AUTHENTICATION, true),
+      maxItems: readInteger(env.MCP_MAX_ITEMS, 100, 'MCP_MAX_ITEMS', { min: 1, max: 500 }),
+      maxResultBytes: readInteger(env.MCP_MAX_RESULT_BYTES, 1_000_000, 'MCP_MAX_RESULT_BYTES', { min: 10_000, max: 10_000_000 }),
+      allowedOrigins: readOriginList(env.MCP_ALLOWED_ORIGINS, studioOrigin),
+      allowedHosts: readHostList(env.MCP_ALLOWED_HOSTS, studioOrigin),
     },
     cache: {
       enabled: readBoolean(env.CACHE_ENABLED, true),
-      store: readCacheStore(env.CACHE_STORE),
-      ttlMs: readInteger(env.CACHE_TTL_MS, 30_000, 'CACHE_TTL_MS', {
-        min: 1,
-        max: 24 * 60 * 60 * 1000,
-      }),
-      maxEntries: readInteger(env.CACHE_MAX_ENTRIES, 5_000, 'CACHE_MAX_ENTRIES', {
-        min: 1,
-        max: 1_000_000,
-      }),
+      store: cacheStore,
+      ttlMs: readInteger(env.CACHE_TTL_MS, 30_000, 'CACHE_TTL_MS', { min: 1, max: 24 * 60 * 60 * 1000 }),
+      maxEntries: readInteger(env.CACHE_MAX_ENTRIES, 5_000, 'CACHE_MAX_ENTRIES', { min: 1, max: 1_000_000 }),
+    },
+    redis: {
+      url: redisUrl,
+      prefix: readString(env.REDIS_PREFIX, 'yuncms:default:'),
+      required: readBoolean(env.REDIS_REQUIRED, false),
+      connectTimeoutMs: readInteger(env.REDIS_CONNECT_TIMEOUT_MS, 5_000, 'REDIS_CONNECT_TIMEOUT_MS', { min: 100, max: 60_000 }),
+      commandTimeoutMs: readInteger(env.REDIS_COMMAND_TIMEOUT_MS, 3_000, 'REDIS_COMMAND_TIMEOUT_MS', { min: 100, max: 60_000 }),
     },
     database: {
       host: readString(env.DB_HOST, '127.0.0.1'),
@@ -109,10 +164,7 @@ export function loadConfig(env = process.env) {
     },
     storage: {
       localRoot: readString(env.FILES_LOCAL_ROOT, '.yuncms/uploads'),
-      maxUploadBytes: readInteger(env.FILES_MAX_UPLOAD_BYTES, 25 * 1024 * 1024, 'FILES_MAX_UPLOAD_BYTES', {
-        min: 1,
-        max: 1024 * 1024 * 1024,
-      }),
+      maxUploadBytes: readInteger(env.FILES_MAX_UPLOAD_BYTES, 25 * 1024 * 1024, 'FILES_MAX_UPLOAD_BYTES', { min: 1, max: 1024 * 1024 * 1024 }),
       s3: {
         bucket: readString(env.S3_BUCKET, ''),
         region: readString(env.S3_REGION, 'us-east-1'),
@@ -123,18 +175,9 @@ export function loadConfig(env = process.env) {
       },
     },
     audit: {
-      retentionDays: readInteger(env.AUDIT_RETENTION_DAYS, 90, 'AUDIT_RETENTION_DAYS', {
-        min: 1,
-        max: 3650,
-      }),
-      cleanupBatchSize: readInteger(env.AUDIT_CLEANUP_BATCH_SIZE, 1000, 'AUDIT_CLEANUP_BATCH_SIZE', {
-        min: 1,
-        max: 5000,
-      }),
-      cleanupMaxBatches: readInteger(env.AUDIT_CLEANUP_MAX_BATCHES, 100, 'AUDIT_CLEANUP_MAX_BATCHES', {
-        min: 1,
-        max: 1000,
-      }),
+      retentionDays: readInteger(env.AUDIT_RETENTION_DAYS, 90, 'AUDIT_RETENTION_DAYS', { min: 1, max: 3650 }),
+      cleanupBatchSize: readInteger(env.AUDIT_CLEANUP_BATCH_SIZE, 1000, 'AUDIT_CLEANUP_BATCH_SIZE', { min: 1, max: 5000 }),
+      cleanupMaxBatches: readInteger(env.AUDIT_CLEANUP_MAX_BATCHES, 100, 'AUDIT_CLEANUP_MAX_BATCHES', { min: 1, max: 1000 }),
     },
     mail: {
       host: readString(env.SMTP_HOST, ''),
@@ -147,6 +190,8 @@ export function loadConfig(env = process.env) {
     auth: {
       publicUrl: readString(env.AUTH_PUBLIC_URL, studioOrigin).replace(/\/$/, ''),
       rateLimit: {
+        store: authRateLimitStore,
+        failureMode: readFailureMode(env.RATE_LIMIT_FAILURE_MODE),
         loginWindowMs: readInteger(env.AUTH_LOGIN_RATE_WINDOW_MS, 60_000, 'AUTH_LOGIN_RATE_WINDOW_MS', { min: 1000, max: 24 * 60 * 60 * 1000 }),
         loginMax: readInteger(env.AUTH_LOGIN_RATE_MAX, 10, 'AUTH_LOGIN_RATE_MAX', { min: 1, max: 100_000 }),
         refreshWindowMs: readInteger(env.AUTH_REFRESH_RATE_WINDOW_MS, 60_000, 'AUTH_REFRESH_RATE_WINDOW_MS', { min: 1000, max: 24 * 60 * 60 * 1000 }),

package/src/hooks.js

@@ -7,49 +7,119 @@ function hookError(code, message) {
   return error;
 }
 
+export const HOOK_EVENTS = Object.freeze({
+  itemQuery: 'items.query',
+  itemRead: 'items.read',
+  itemCreate: 'items.create',
+  itemUpdate: 'items.update',
+  itemDelete: 'items.delete',
+  fileCreate: 'files.create',
+  fileUpdate: 'files.update',
+  fileDelete: 'files.delete',
+  fileRead: 'files.read',
+  userCreate: 'users.create',
+  userUpdate: 'users.update',
+  userDelete: 'users.delete',
+  userPasswordUpdate: 'users.password.update',
+  roleCreate: 'roles.create',
+  roleUpdate: 'roles.update',
+  roleDelete: 'roles.delete',
+  permissionCreate: 'permissions.create',
+  permissionUpdate: 'permissions.update',
+  permissionDelete: 'permissions.delete',
+  schemaCollectionCreate: 'schema.collection.create',
+  schemaCollectionUpdate: 'schema.collection.update',
+  schemaCollectionDelete: 'schema.collection.delete',
+  schemaFieldCreate: 'schema.field.create',
+  schemaFieldUpdate: 'schema.field.update',
+  schemaFieldDelete: 'schema.field.delete',
+  schemaRelationCreate: 'schema.relation.create',
+  schemaRelationDelete: 'schema.relation.delete',
+  schemaChanged: 'schema.changed',
+  authLoginSuccess: 'auth.login.success',
+  authLoginFailed: 'auth.login.failed',
+  authRefreshSuccess: 'auth.refresh.success',
+  authLogout: 'auth.logout',
+  mailSend: 'mail.send',
+  mailSent: 'mail.sent',
+  mailFailed: 'mail.failed',
+  requestReceived: 'request.received',
+  requestCompleted: 'request.completed',
+  requestFailed: 'request.failed',
+  appBeforeStart: 'app.beforeStart',
+  appAfterStart: 'app.afterStart',
+  appBeforeStop: 'app.beforeStop',
+  appAfterStop: 'app.afterStop',
+});
+
+function normalizeRegistrationOptions(options = {}) {
+  const priority = options?.priority ?? 0;
+  if (!Number.isInteger(priority) || priority < -10_000 || priority > 10_000) {
+    throw new Error('Hook priority must be an integer between -10000 and 10000');
+  }
+  return {
+    priority,
+    extensionId: typeof options?.extensionId === 'string' && options.extensionId.trim()
+      ? options.extensionId.trim()
+      : 'core',
+  };
+}
+
 export class HookEmitter {
-  constructor({ maxDepth = 12 } = {}) {
+  constructor({ maxDepth = 12, logger = console } = {}) {
     if (!Number.isInteger(maxDepth) || maxDepth < 1 || maxDepth > 100) {
       throw new Error('Hook maxDepth must be an integer between 1 and 100');
     }
 
     this.maxDepth = maxDepth;
+    this.logger = logger;
     this.filters = new Map();
     this.actions = new Map();
     this.initializers = new Map();
     this.storage = new AsyncLocalStorage();
+    this.registrationIndex = 0;
   }
 
-  registerFilter(event, handler) {
-    return this.#register(this.filters, event, handler);
+  registerFilter(event, handler, options = {}) {
+    return this.#register(this.filters, event, handler, options);
   }
 
-  registerAction(event, handler) {
-    return this.#register(this.actions, event, handler);
+  registerAction(event, handler, options = {}) {
+    return this.#register(this.actions, event, handler, options);
   }
 
-  registerInit(event, handler) {
-    return this.#register(this.initializers, event, handler);
+  registerInit(event, handler, options = {}) {
+    return this.#register(this.initializers, event, handler, options);
   }
 
-  #register(map, event, handler) {
+  #register(map, event, handler, options) {
     if (typeof event !== 'string' || event.trim() === '') throw new Error('Hook event is required');
     if (typeof handler !== 'function') throw new Error(`Hook handler for ${event} must be a function`);
 
     const name = event.trim();
+    const registration = {
+      handler,
+      ...normalizeRegistrationOptions(options),
+      index: this.registrationIndex++,
+    };
     const handlers = map.get(name) ?? [];
-    handlers.push(handler);
+    handlers.push(registration);
+    handlers.sort((left, right) => (
+      right.priority - left.priority
+      || left.extensionId.localeCompare(right.extensionId)
+      || left.index - right.index
+    ));
     map.set(name, handlers);
 
     return () => {
       const active = map.get(name) ?? [];
-      const next = active.filter((candidate) => candidate !== handler);
+      const next = active.filter((candidate) => candidate !== registration);
       if (next.length === 0) map.delete(name);
       else map.set(name, next);
     };
   }
 
-  #nextExecution(event) {
+  #nextExecution(event, registration = null) {
     const current = this.storage.getStore();
     const depth = (current?.depth ?? 0) + 1;
     if (depth > this.maxDepth) {
@@ -62,12 +132,15 @@ export class HookEmitter {
     return {
       chainId: current?.chainId ?? randomUUID(),
       depth,
+      stack: [...(current?.stack ?? []), event],
       events: [...(current?.events ?? []), event],
+      originExtension: current?.originExtension ?? registration?.extensionId ?? null,
+      originEvent: current?.originEvent ?? event,
     };
   }
 
-  async #runWithExecution(event, operation) {
-    const execution = this.#nextExecution(event);
+  async #runWithExecution(event, registration, operation) {
+    const execution = this.#nextExecution(event, registration);
     return this.storage.run(execution, () => operation(execution));
   }
 
@@ -75,47 +148,59 @@ export class HookEmitter {
     const handlers = this.filters.get(event) ?? [];
     if (handlers.length === 0) return payload;
 
-    return this.#runWithExecution(event, async (execution) => {
-      let current = payload;
-      for (const handler of handlers) {
-        const next = await handler(current, {
+    let current = payload;
+    for (const registration of handlers) {
+      current = await this.#runWithExecution(event, registration, async (execution) => {
+        const next = await registration.handler(current, {
           ...context,
           hook: execution,
           event,
+          extensionId: registration.extensionId,
         });
-        if (next !== undefined) current = next;
-      }
-      return current;
-    });
+        return next === undefined ? current : next;
+      });
+    }
+    return current;
   }
 
   async action(event, payload, context = {}) {
     const handlers = this.actions.get(event) ?? [];
     if (handlers.length === 0) return;
 
-    await this.#runWithExecution(event, async (execution) => {
-      for (const handler of handlers) {
-        await handler(payload, {
-          ...context,
-          hook: execution,
+    for (const registration of handlers) {
+      try {
+        await this.#runWithExecution(event, registration, async (execution) => {
+          await registration.handler(payload, {
+            ...context,
+            hook: execution,
+            event,
+            extensionId: registration.extensionId,
+          });
+        });
+      } catch (error) {
+        this.logger?.error?.('YunCMS extension action failed after successful lifecycle point', {
           event,
+          extensionId: registration.extensionId,
+          code: error?.code ?? null,
+          message: error?.message ?? String(error),
         });
       }
-    });
+    }
   }
 
   async init(event, context = {}) {
     const handlers = this.initializers.get(event) ?? [];
     if (handlers.length === 0) return;
 
-    await this.#runWithExecution(`init:${event}`, async (execution) => {
-      for (const handler of handlers) {
-        await handler({
+    for (const registration of handlers) {
+      await this.#runWithExecution(`init:${event}`, registration, async (execution) => {
+        await registration.handler({
           ...context,
           hook: execution,
           event,
+          extensionId: registration.extensionId,
         });
-      }
-    });
+      });
+    }
   }
 }

package/src/index.js

@@ -1,5 +1,12 @@
 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';
@@ -19,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';
@@ -44,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';
@@ -76,10 +87,15 @@ export {
   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 {