@claudelaw/taichu 0.6.0

package/packages/server/src/index.js

@@ -0,0 +1,195 @@
+/**
+ * @taichu/server — Taichu HTTP Server
+ *
+ * 零外部依赖的 HTTP 服务。
+ * 负责：
+ *   1. 路由分发
+ *   2. JSON 解析
+ *   3. CORS 处理
+ *   4. 静态文件服务（管理后台 SPA）
+ *   5. MCP 端点（Phase 2）
+ *
+ * 设计原则：
+ *   - 每个模块可独立测试
+ *   - 错误统一捕获并序列化为 JSON
+ *   - 请求上下文通过 context object 传递
+ */
+
+import { createServer } from 'node:http';
+import { router } from './router.js';
+import { parseBody } from './body-parser.js';
+import { corsMiddleware } from './middleware/cors.js';
+import { errorHandler } from './middleware/error-handler.js';
+import { createContext } from './context.js';
+import { bootstrap } from './bootstrap.js';
+import { initSearch } from './search.js';
+import { logger } from './logger.js';
+import { loadConfig, getConfig, getConfigWarnings, configSummary } from './config.js';
+import { getWSS } from './websocket.js';
+import { getWebhookManager } from './webhook.js';
+import { rateLimit } from './middleware/rate-limit.js';
+import { record as auditRecord } from './audit.js';
+import { snapshotRevision } from './revisions.js';
+import { notify } from './notify.js';
+import { startScheduler, stopScheduler } from './scheduler.js';
+
+export async function start(configOverrides = {}) {
+  const config = loadConfig();
+  const { port, host, storage, dataDir, version } = config;
+
+  // Pre-init store so the first request doesn't pay cold-start cost
+  const ctx = await createContext({ req: null, res: null, url: null, body: null, config: { storage, dataDir } });
+  const storeType = ctx.store.getDbPath ? `sqlite (${ctx.store.getDbPath()})` : 'memory';
+
+  // Init vector search index
+  await initSearch(ctx.store, ctx.hooks);
+
+  // Init WebSocket for real-time updates
+  const wss = getWSS();
+
+  // Init webhook manager
+  const webhooks = getWebhookManager(ctx.store);
+
+  // Init scheduled publishing scheduler
+  startScheduler(ctx.hooks);
+
+  // Register content change broadcasts via hooks
+  for (const event of ['afterCreate', 'afterUpdate', 'afterDelete']) {
+    ctx.hooks.on(event, async (doc) => {
+      const wsEvent = event.replace('after', '').toLowerCase();
+      const payload = {
+        id: doc.id, type: doc.type, status: doc.status,
+        title: doc.data?.title || doc.data?.name || '',
+        updatedAt: doc.updatedAt
+      };
+
+      // WebSocket broadcast
+      wss.broadcast(doc.type || '*', wsEvent, payload);
+
+      // Webhook fire (async, don't block)
+      webhooks.fire(wsEvent, { ...payload, data: doc.data }).catch(() => {});
+
+      // Audit log (async, don't block)
+      auditRecord({
+        actorId: doc.createdBy || doc._meta?.createdBy?.agentId || 'system',
+        actorType: doc._meta?.createdBy?.type || 'system',
+        action: wsEvent,
+        resourceType: doc.type,
+        resourceId: doc.id,
+        detail: { title: doc.data?.title, status: doc.status }
+      }).catch(() => {});
+
+      // Snapshot revision (async, don't block)
+      if (wsEvent !== 'delete') {
+        snapshotRevision(doc, { id: doc.createdBy || 'system' }).catch(() => {});
+      }
+
+      // IM notification (async, don't block)
+      notify(`content_${wsEvent}d`, { doc, summary: payload.title || '' }).catch(() => {});
+    });
+  }
+
+  const server = createServer(async (req, res) => {
+    try {
+      // 1. CORS
+      corsMiddleware(req, res);
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      // 2. Parse URL
+      const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+
+      // 3. Rate limit (skip for health, static files)
+      if (!url.pathname.startsWith('/admin') && !url.pathname.startsWith('/uploads') && url.pathname !== '/health' && url.pathname !== '/ws-test.html') {
+        const ctx = { req, res, url };
+        if (!rateLimit(ctx)) return; // 429 already written
+      }
+
+      // 3. Parse body (for POST/PUT/PATCH)
+      let body = null;
+      if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
+        body = await parseBody(req);
+      }
+
+      // 4. Build context (reuses pre-initialized store)
+      const ctx2 = await createContext({ req, res, url, body, config: { storage, dataDir } });
+
+      // 5. Route
+      await router(ctx2);
+
+    } catch (err) {
+      errorHandler(res, err);
+    }
+  });
+
+  // Attach WebSocket to HTTP server
+  wss.attach(server);
+
+  server.listen(port, host, () => {
+    const startMsg = [
+      '',
+      '  ██████╗ ██╗ ██████╗ ███╗   ██╗',
+      ' ██╔════╝ ██║██╔═══██╗████╗  ██║',
+      ' ██║  ███╗██║██║   ██║██╔██╗ ██║',
+      ' ██║   ██║██║██║   ██║██║╚██╗██║',
+      ' ╚██████╔╝██║╚██████╔╝██║ ╚████║',
+      '  ╚═════╝ ╚═╝ ╚═════╝ ╚═╝  ╚═══╝',
+      '',
+      `  Taichu CMS v${version}`,
+      `  AI Agent-Native Content Infrastructure`,
+      `  Store:     ${storeType}`,
+      '',
+      `  Local:   http://localhost:${port}`,
+      `  Network: http://${host}:${port}`,
+      '',
+      `  API:     http://localhost:${port}/api`,
+      `  Health:  http://localhost:${port}/api/health`,
+      `  Live:    ws://localhost:${port}`,
+      '',
+      `  Ready.`,
+      ''
+    ].join('\n');
+    console.log(startMsg);
+  });
+
+  // Graceful shutdown
+  const shutdown = async (signal) => {
+    logger.info(`${signal} received. Shutting down...`);
+    stopScheduler();
+    wss.close();
+    server.close(() => {
+      logger.info('HTTP server closed');
+      // Flush store if needed
+      if (ctx.store.flush) {
+        ctx.store.flush().then(() => process.exit(0)).catch(() => process.exit(0));
+      } else {
+        process.exit(0);
+      }
+    });
+    // Force exit after 10s
+    setTimeout(() => process.exit(1), 10000);
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+
+  server.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+      console.error(`Port ${port} is already in use. Try: TAICHU_PORT=${port + 1} npm start`);
+    } else {
+      console.error('Server error:', err.message);
+    }
+    process.exit(1);
+  });
+
+  return server;
+}
+
+// Run directly if called as main module
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, '/'))) {
+  bootstrap();
+  await start({});
+}

package/packages/server/src/logger.js

@@ -0,0 +1,78 @@
+/**
+ * Logger — 结构化日志系统
+ *
+ * JSON 格式输出，支持分级和请求追踪。
+ *
+ * 级别（数值越小越详细）：
+ *   debug: 0 — 开发调试
+ *   info:  1 — 常规信息
+ *   warn:  2 — 警告
+ *   error: 3 — 错误
+ *
+ * 环境变量：
+ *   TAICHU_LOG_LEVEL  — 最小输出级别（默认 info）
+ *   TAICHU_LOG_FORMAT — "json" | "pretty"（默认 pretty）
+ */
+
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+const LEVEL_LABELS = ['DEBUG', 'INFO', 'WARN', 'ERROR'];
+
+// ANSI 颜色（pretty 模式）
+const COLORS = {
+  debug: '\x1b[90m',  // gray
+  info:  '\x1b[36m',  // cyan
+  warn:  '\x1b[33m',  // yellow
+  error: '\x1b[31m',  // red
+  reset: '\x1b[0m',
+  dim:   '\x1b[2m',
+  bold:  '\x1b[1m'
+};
+
+const minLevel = LEVELS[process.env.TAICHU_LOG_LEVEL || 'info'] ?? 1;
+const format = process.env.TAICHU_LOG_FORMAT || 'pretty';
+
+/**
+ * @param {string} level
+ * @param {string} message
+ * @param {object} [context]
+ */
+function log(level, message, context = {}) {
+  if (LEVELS[level] < minLevel) return;
+
+  const ts = new Date().toISOString();
+
+  if (format === 'json') {
+    const entry = { ts, level, message, ...context };
+    console.log(JSON.stringify(entry));
+    return;
+  }
+
+  // Pretty format
+  const color = COLORS[level] || '';
+  const label = level.toUpperCase().padEnd(5);
+  const extra = Object.keys(context).length
+    ? COLORS.dim + ' ' + JSON.stringify(context) + COLORS.reset
+    : '';
+
+  console.log(`${COLORS.dim}${ts}${COLORS.reset} ${color}${COLORS.bold}${label}${COLORS.reset} ${message}${extra}`);
+}
+
+export const logger = {
+  debug: (msg, ctx) => log('debug', msg, ctx),
+  info:  (msg, ctx) => log('info', msg, ctx),
+  warn:  (msg, ctx) => log('warn', msg, ctx),
+  error: (msg, ctx) => log('error', msg, ctx)
+};
+
+/**
+ * Create a child logger with a fixed namespace.
+ * Usage: const log = logger.child('store'); log.info('connected');
+ */
+export function createLogger(namespace) {
+  return {
+    debug: (msg, ctx) => logger.debug(`[${namespace}] ${msg}`, ctx),
+    info:  (msg, ctx) => logger.info(`[${namespace}] ${msg}`, ctx),
+    warn:  (msg, ctx) => logger.warn(`[${namespace}] ${msg}`, ctx),
+    error: (msg, ctx) => logger.error(`[${namespace}] ${msg}`, ctx)
+  };
+}

package/packages/server/src/media-store.js

@@ -0,0 +1,213 @@
+/**
+ * Media Store — 文件存储抽象
+ *
+ * 支持：
+ *   - 本地文件系统存储（接口设计为未来扩展 S3/R2 等）
+ *   - 图片自动压缩（quality 可配置）
+ *   - WebP 自动转换（原格式保留，额外生成 .webp 版本）
+ *   - 多尺寸缩略图（small/medium/large）
+ */
+
+import { writeFile, readFile, mkdir, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { createHash } from 'node:crypto';
+import sharp from 'sharp';
+
+const DEFAULT_UPLOAD_DIR = join(process.cwd(), '.taichu', 'uploads');
+
+// Thumbnail sizes: name → max dimension
+const THUMB_SIZES = {
+  small:  150,
+  medium: 300,
+  large:  800
+};
+
+// Image compression settings
+const COMPRESS_QUALITY = parseInt(process.env.TAICHU_IMAGE_QUALITY) || 80;
+const WEBP_QUALITY = parseInt(process.env.TAICHU_WEBP_QUALITY) || 75;
+const MAX_IMAGE_DIMENSION = parseInt(process.env.TAICHU_MAX_IMAGE_DIMENSION) || 4096;
+const ENABLE_WEBP = process.env.TAICHU_WEBP !== '0'; // default: enabled
+const ENABLE_COMPRESS = process.env.TAICHU_IMAGE_COMPRESS !== '0'; // default: enabled
+
+/**
+ * @param {object} config
+ * @param {string} [config.uploadDir]
+ */
+export function createMediaStore(config = {}) {
+  const uploadDir = config.uploadDir || process.env.TAICHU_UPLOAD_DIR || DEFAULT_UPLOAD_DIR;
+  const thumbDir = join(uploadDir, 'thumbnails');
+
+  let initialized = false;
+
+  async function ensureDirs() {
+    if (initialized) return;
+    if (!existsSync(uploadDir)) await mkdir(uploadDir, { recursive: true });
+    for (const size of Object.keys(THUMB_SIZES)) {
+      const dir = join(uploadDir, 'thumbnails', size);
+      if (!existsSync(dir)) await mkdir(dir, { recursive: true });
+    }
+    // WebP output dir
+    const webpDir = join(uploadDir, 'webp');
+    if (!existsSync(webpDir)) await mkdir(webpDir, { recursive: true });
+    initialized = true;
+  }
+
+  /**
+   * Save a file with image processing pipeline:
+   *   1. Compress original (if image & enabled)
+   *   2. Generate WebP variant (if image & enabled)
+   *   3. Generate multi-size thumbnails
+   *
+   * @param {Buffer} buffer
+   * @param {string} filename
+   * @param {string} mimetype
+   * @returns {Promise<object>}
+   */
+  async function save(buffer, filename, mimetype) {
+    await ensureDirs();
+
+    const ext = extname(filename) || mimetypeToExt(mimetype) || '.bin';
+    const hash = createHash('md5').update(buffer).digest('hex').substring(0, 12);
+    const safeFilename = `${hash}${ext}`;
+    const filePath = join(uploadDir, safeFilename);
+
+    const result = {
+      id: hash,
+      url: `/uploads/${safeFilename}`,
+      filename: safeFilename,
+      originalName: filename,
+      mimetype,
+      size: buffer.length,
+      thumbnails: {},
+      webp: null
+    };
+
+    const isProcessableImage = mimetype.startsWith('image/')
+      && mimetype !== 'image/svg+xml'
+      && mimetype !== 'image/gif';
+
+    if (isProcessableImage) {
+      try {
+        const pipeline = sharp(buffer);
+        const metadata = await pipeline.metadata();
+        result.width = metadata.width;
+        result.height = metadata.height;
+
+        // Step 1: Compress original if enabled
+        let finalBuffer = buffer;
+        if (ENABLE_COMPRESS && metadata.width && metadata.width > MAX_IMAGE_DIMENSION) {
+          finalBuffer = await pipeline
+            .resize(MAX_IMAGE_DIMENSION, MAX_IMAGE_DIMENSION, { fit: 'inside', withoutEnlargement: true })
+            .toBuffer();
+          result.size = finalBuffer.length;
+          result.compressed = true;
+        } else if (ENABLE_COMPRESS && (mimetype === 'image/jpeg' || mimetype === 'image/png')) {
+          // Compress without resize
+          let compressor = sharp(buffer);
+          if (mimetype === 'image/jpeg') {
+            compressor = compressor.jpeg({ quality: COMPRESS_QUALITY, mozjpeg: true });
+          } else {
+            compressor = compressor.png({ quality: COMPRESS_QUALITY, compressionLevel: 8 });
+          }
+          const compressed = await compressor.toBuffer();
+          if (compressed.length < buffer.length) {
+            finalBuffer = compressed;
+            result.size = finalBuffer.length;
+            result.compressed = true;
+          }
+        }
+
+        await writeFile(filePath, finalBuffer);
+
+        // Step 2: Generate WebP variant
+        if (ENABLE_WEBP) {
+          const webpFilename = `${hash}.webp`;
+          const webpPath = join(uploadDir, 'webp', webpFilename);
+          await sharp(finalBuffer)
+            .webp({ quality: WEBP_QUALITY })
+            .toFile(webpPath);
+          result.webp = `/uploads/webp/${webpFilename}`;
+        }
+
+        // Step 3: Generate multi-size thumbnails
+        for (const [sizeName, maxDim] of Object.entries(THUMB_SIZES)) {
+          const thumbFilename = `${sizeName}_${hash}${ENABLE_WEBP ? '.webp' : ext}`;
+          const thumbPath = join(uploadDir, 'thumbnails', sizeName, thumbFilename);
+
+          let thumbPipeline = sharp(finalBuffer).resize(maxDim, maxDim, { fit: 'inside', withoutEnlargement: true });
+          if (ENABLE_WEBP) {
+            thumbPipeline = thumbPipeline.webp({ quality: WEBP_QUALITY });
+          } else if (mimetype === 'image/jpeg') {
+            thumbPipeline = thumbPipeline.jpeg({ quality: 75 });
+          } else {
+            thumbPipeline = thumbPipeline.png({ quality: 75 });
+          }
+
+          await thumbPipeline.toFile(thumbPath);
+          result.thumbnails[sizeName] = `/uploads/thumbnails/${sizeName}/${thumbFilename}`;
+        }
+      } catch (e) {
+        // Non-processable image — save as-is
+        await writeFile(filePath, buffer);
+      }
+    } else {
+      // Non-image or SVG/GIF — save as-is
+      await writeFile(filePath, buffer);
+    }
+
+    return result;
+  }
+
+  /**
+   * Delete a file and all its variants (thumbnails, WebP).
+   */
+  async function remove(safeFilename) {
+    const filePath = join(uploadDir, safeFilename);
+    if (existsSync(filePath)) await unlink(filePath);
+
+    // Remove WebP variant
+    const hash = safeFilename.replace(/\.[^.]+$/, '');
+    const webpPath = join(uploadDir, 'webp', `${hash}.webp`);
+    if (existsSync(webpPath)) await unlink(webpPath);
+
+    // Remove all thumbnail sizes
+    for (const sizeName of Object.keys(THUMB_SIZES)) {
+      const dir = join(uploadDir, 'thumbnails', sizeName);
+      // Try both original ext and webp
+      const ext = extname(safeFilename);
+      const thumbOrig = join(dir, `${sizeName}_${safeFilename}`);
+      const thumbWebp = join(dir, `${sizeName}_${hash}.webp`);
+      if (existsSync(thumbOrig)) await unlink(thumbOrig);
+      if (existsSync(thumbWebp)) await unlink(thumbWebp);
+    }
+  }
+
+  /**
+   * Read a file from disk.
+   */
+  async function get(safeFilename) {
+    const filePath = join(uploadDir, safeFilename);
+    if (!existsSync(filePath)) return null;
+    return readFile(filePath);
+  }
+
+  return { save, remove, get, uploadDir, thumbDir };
+}
+
+function mimetypeToExt(mimetype) {
+  const map = {
+    'image/jpeg': '.jpg',
+    'image/png': '.png',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+    'image/svg+xml': '.svg',
+    'video/mp4': '.mp4',
+    'video/webm': '.webm',
+    'audio/mpeg': '.mp3',
+    'audio/wav': '.wav',
+    'application/pdf': '.pdf',
+    'application/zip': '.zip'
+  };
+  return map[mimetype] || null;
+}

package/packages/server/src/middleware/auth.js

@@ -0,0 +1,203 @@
+/**
+ * Auth Middleware — 认证中间件
+ *
+ * 两种认证方式：
+ *   Bearer <JWT>        → 解析 JWT，识别人类用户
+ *   X-Taichu-Agent-Key    → 匹配 API Key，识别 AI Agent
+ *
+ * 使用：
+ *   const result = await requireAuth(ctx);
+ *   if (!result.authenticated) return error;
+ *   ctx.actor = result.actor; // { id, type: 'human'|'agent', username, role }
+ */
+
+import { verifyJWT, verifyAPIKey } from '../../../core/src/auth.js';
+import { getStore } from '../context.js';
+import { randomBytes } from 'node:crypto';
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Cached JWT secret for the process lifetime */
+let _jwtSecret = null;
+
+/**
+ * Get or auto-generate a JWT secret.
+ *
+ * Priority:
+ *   1. TAICHU_JWT_SECRET environment variable
+ *   2. Auto-generated secret persisted to .taichu/data/.jwt_secret
+ *
+ * The hardcoded default 'taichu-dev-secret' is explicitly rejected.
+ *
+ * @returns {string}
+ */
+export function getJwtSecret() {
+  if (_jwtSecret) return _jwtSecret;
+
+  // 1. Environment variable
+  const envSecret = process.env.TAICHU_JWT_SECRET;
+  if (envSecret && envSecret !== 'taichu-dev-secret' && envSecret !== 'change-me') {
+    _jwtSecret = envSecret;
+    return _jwtSecret;
+  }
+
+  // 2. Auto-generate and persist
+  const dataDir = process.env.TAICHU_DATA_DIR || join(process.cwd(), '.taichu', 'data');
+  const secretFile = join(dataDir, '.jwt_secret');
+
+  if (existsSync(secretFile)) {
+    _jwtSecret = readFileSync(secretFile, 'utf-8').trim();
+    if (_jwtSecret) return _jwtSecret;
+  }
+
+  // Generate new secret
+  if (!existsSync(dataDir)) {
+    mkdirSync(dataDir, { recursive: true });
+  }
+  _jwtSecret = randomBytes(32).toString('hex');
+  writeFileSync(secretFile, _jwtSecret, 'utf-8');
+
+  console.log(`  Auth: Auto-generated JWT secret saved to ${secretFile}`);
+  return _jwtSecret;
+}
+
+/**
+ * Require authentication — returns auth result or 401.
+ *
+ * @param {Context} ctx
+ * @returns {Promise<{ authenticated: boolean, status?: number, error?: string, message?: string, actor?: object }>}
+ */
+export async function requireAuth(ctx) {
+  const authHeader = ctx.req.headers['authorization'];
+  const agentKey = ctx.req.headers['x-taichu-agent-key'];
+
+  // ── JWT Auth (Human) ──
+  if (authHeader && authHeader.startsWith('Bearer ')) {
+    const token = authHeader.slice(7);
+    const secret = getJwtSecret();
+    const result = verifyJWT(token, secret);
+
+    if (!result.valid) {
+      return { authenticated: false, status: 401, error: 'UNAUTHORIZED', message: result.error };
+    }
+
+    return {
+      authenticated: true,
+      actor: {
+        id: result.payload.sub,
+        type: 'human',
+        username: result.payload.username,
+        role: result.payload.role || 'author'
+      }
+    };
+  }
+
+  // ── API Key Auth (Agent) ──
+  if (agentKey) {
+    const store = getStore();
+    const keys = await store.list({ type: 'api_key', status: 'active' });
+
+    for (const keyDoc of keys) {
+      if (verifyAPIKey(agentKey, keyDoc.data.hash)) {
+        const scopes = keyDoc.data.scopes || ['*:*']; // default: full access for legacy keys
+        return {
+          authenticated: true,
+          actor: {
+            id: keyDoc.data.ownerId || `agent_${keyDoc.data.prefix}`,
+            type: 'agent',
+            role: 'agent',
+            keyPrefix: keyDoc.data.prefix,
+            label: keyDoc.data.label,
+            scopes
+          }
+        };
+      }
+    }
+
+    return { authenticated: false, status: 401, error: 'UNAUTHORIZED', message: 'Invalid API key' };
+  }
+
+  // ── No credentials ──
+  return { authenticated: false, status: 401, error: 'UNAUTHORIZED', message: 'Authentication required' };
+}
+
+/**
+ * Check if the actor has the required scope.
+ *
+ * Scope format: "<type>:<action>" where:
+ *   - type: content type name (e.g. "article") or "*" for all
+ *   - action: "read" | "write" | "delete" | "*" for all
+ *
+ * Examples:
+ *   checkScope(actor, 'article:read')  → true if actor can read articles
+ *   checkScope(actor, '*:*')           → true if actor is admin
+ *   checkScope(actor, 'media:write')   → true if actor can write media
+ *
+ * Humans (JWT) always have full access (*:*).
+ *
+ * @param {object} actor
+ * @param {string} required — scope string like "article:read"
+ * @returns {boolean}
+ */
+export function checkScope(actor, required) {
+  // Humans always pass
+  if (actor.type === 'human') return true;
+
+  const scopes = actor.scopes || [];
+  if (scopes.includes('*:*')) return true;
+
+  // Parse required: "type:action" or "type:field:action"
+  const parts = required.split(':');
+  const reqType = parts[0];
+  const reqField = parts.length === 3 ? parts[1] : null;
+  const reqAction = parts.length === 3 ? parts[2] : parts[1];
+
+  for (const scope of scopes) {
+    const sParts = scope.split(':');
+
+    if (sParts.length === 3) {
+      // Field-level scope: type:field:action
+      const typeMatch = sParts[0] === '*' || sParts[0] === reqType;
+      const fieldMatch = sParts[1] === '*' || (reqField && sParts[1] === reqField);
+      const actionMatch = sParts[2] === '*' || sParts[2] === reqAction;
+      if (typeMatch && fieldMatch && (reqField ? true : true) && actionMatch) return true;
+    } else {
+      // Type-level scope: type:action
+      const typeMatch = sParts[0] === '*' || sParts[0] === reqType;
+      const actionMatch = sParts[1] === '*' || sParts[1] === reqAction;
+      if (typeMatch && actionMatch) return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Convenience: require auth + scope check in one call.
+ * Returns 403 if authenticated but lacking scope.
+ */
+export async function requireScopedAuth(ctx, scope) {
+  const result = await requireAuth(ctx);
+  if (!result.authenticated) return result;
+
+  if (!checkScope(result.actor, scope)) {
+    return {
+      authenticated: false,
+      status: 403,
+      error: 'FORBIDDEN',
+      message: `Insufficient permissions: "${scope}" scope required`
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Optional auth — attaches actor if authenticated, but doesn't block.
+ */
+export async function optionalAuth(ctx) {
+  const result = await requireAuth(ctx);
+  if (result.authenticated) {
+    ctx.actor = result.actor;
+  }
+}