coding-tool-x 3.8.4 → 3.8.6

package/src/platforms/drivers/secure-file-driver.js

@@ -0,0 +1,272 @@
+'use strict';
+
+const fs = require('fs/promises');
+const { constants: FS_CONSTANTS } = require('fs');
+const crypto = require('crypto');
+const path = require('path');
+
+let temporaryFileCounter = 0;
+const NOFOLLOW_FLAG = FS_CONSTANTS.O_NOFOLLOW || 0;
+
+function createFailure({ platform, capability, operation, error }) {
+  const result = {
+    status: 'failed',
+    platform,
+    capability,
+    operation,
+    error: error && error.message ? error.message : String(error)
+  };
+  if (error) Object.defineProperty(result, 'cause', { value: error, enumerable: false });
+  return result;
+}
+
+function isInside(root, candidate) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function isSystemAlias(current, realpath) {
+  return (current === '/var' && realpath === '/private/var') ||
+    (current === '/tmp' && realpath === '/private/tmp') ||
+    (current === '/etc' && realpath === '/private/etc');
+}
+
+async function canonicalPath(fsImpl, target) {
+  const resolved = path.resolve(target);
+  if (typeof fsImpl.realpath !== 'function') return resolved;
+  const missing = [];
+  let current = resolved;
+  while (true) {
+    try {
+      return path.join(await fsImpl.realpath(current), ...missing.reverse());
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      const parent = path.dirname(current);
+      if (parent === current) throw error;
+      missing.push(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+async function assertSafePath(fsImpl, target, home, labels, allowMissing = false) {
+  if (typeof fsImpl.lstat !== 'function') return;
+  const checkComponents = async value => {
+    const resolved = path.resolve(value);
+    const root = path.parse(resolved).root;
+    const parts = path.relative(root, resolved).split(path.sep).filter(Boolean);
+    let current = root;
+    let missing = false;
+    for (const part of parts) {
+      current = path.join(current, part);
+      try {
+        const stat = await fsImpl.lstat(current);
+        if (typeof stat.isSymbolicLink === 'function' && stat.isSymbolicLink()) {
+          const real = typeof fsImpl.realpath === 'function' ? await fsImpl.realpath(current) : '';
+          if (!isSystemAlias(current, real)) throw new Error(labels.pathContainsSymlink(current));
+        }
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+        missing = true;
+      }
+    }
+    if (missing && !allowMissing) {
+      const error = new Error(labels.pathDoesNotExist(resolved));
+      error.code = 'ENOENT';
+      throw error;
+    }
+  };
+  if (!home) {
+    await checkComponents(target);
+    return;
+  }
+  await checkComponents(home);
+  await checkComponents(target);
+  const canonicalHome = await canonicalPath(fsImpl, home);
+  const canonicalTarget = await canonicalPath(fsImpl, target);
+  if (!isInside(canonicalHome, canonicalTarget)) throw new Error(labels.mappingEscapesHome);
+}
+
+async function createCanonicalTarget(fsImpl, target, home, labels, allowMissing) {
+  await assertSafePath(fsImpl, target, home, labels, allowMissing);
+  const canonicalHome = home ? await canonicalPath(fsImpl, home) : null;
+  const canonicalTarget = await canonicalPath(fsImpl, target);
+  const canonicalParent = await canonicalPath(fsImpl, path.dirname(target));
+  if (canonicalHome && (!isInside(canonicalHome, canonicalParent) || !isInside(canonicalHome, canonicalTarget))) {
+    throw new Error(labels.mappingEscapesHome);
+  }
+  return { target: canonicalTarget, parent: canonicalParent, home: canonicalHome };
+}
+
+async function revalidateCanonicalTarget(fsImpl, canonical, target, home, labels) {
+  const currentParent = await canonicalPath(fsImpl, path.dirname(target));
+  const currentTarget = await canonicalPath(fsImpl, target);
+  const currentHome = home ? await canonicalPath(fsImpl, home) : null;
+  if (currentParent !== canonical.parent || currentTarget !== canonical.target || currentHome !== canonical.home) {
+    throw new Error(labels.targetChanged);
+  }
+  await assertSafePath(fsImpl, target, home, labels, true);
+}
+
+function sameFileIdentity(first, second) {
+  return first && second && first.dev !== undefined && first.ino !== undefined &&
+    first.dev === second.dev && first.ino === second.ino;
+}
+
+async function readFileByDescriptor(fsImpl, target, home, labels) {
+  const canonical = await createCanonicalTarget(fsImpl, target, home, labels, false);
+  if (typeof fsImpl.open !== 'function') throw new Error(labels.descriptorReadUnavailable);
+  const handle = await fsImpl.open(canonical.target, FS_CONSTANTS.O_RDONLY | NOFOLLOW_FLAG);
+  try {
+    const descriptorStat = typeof handle.stat === 'function'
+      ? await handle.stat()
+      : (typeof fsImpl.fstat === 'function' ? await fsImpl.fstat(handle.fd) : null);
+    if (!descriptorStat) throw new Error(labels.descriptorIdentityUnavailable);
+    await revalidateCanonicalTarget(fsImpl, canonical, target, home, labels);
+    const pathStat = await fsImpl.lstat(canonical.target);
+    if (typeof pathStat.isSymbolicLink === 'function' && pathStat.isSymbolicLink()) {
+      throw new Error(labels.pathContainsSymlink(canonical.target));
+    }
+    if (!sameFileIdentity(descriptorStat, pathStat)) throw new Error(labels.targetChanged);
+    return await handle.readFile('utf8');
+  } finally {
+    await handle.close();
+  }
+}
+
+async function ensureDirectory(fsImpl, directory, canonicalHome, labels) {
+  if (typeof fsImpl.lstat !== 'function') {
+    await fsImpl.mkdir(directory, { recursive: true });
+    return;
+  }
+  const resolved = path.resolve(directory);
+  const root = path.parse(resolved).root;
+  let current = root;
+  const assertDirectory = async (component, stat) => {
+    if (typeof stat.isSymbolicLink === 'function' && stat.isSymbolicLink()) {
+      const real = typeof fsImpl.realpath === 'function' ? await fsImpl.realpath(component) : '';
+      if (!isSystemAlias(component, real)) throw new Error(labels.pathComponentNotDirectory(component));
+    } else if (typeof stat.isDirectory === 'function' && !stat.isDirectory()) {
+      throw new Error(labels.pathComponentNotDirectory(component));
+    }
+  };
+  for (const part of path.relative(root, resolved).split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    try {
+      await assertDirectory(current, await fsImpl.lstat(current));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      try {
+        await fsImpl.mkdir(current, { mode: 0o700 });
+      } catch (mkdirError) {
+        if (mkdirError.code !== 'EEXIST') throw mkdirError;
+      }
+      await assertDirectory(current, await fsImpl.lstat(current));
+    }
+  }
+  if (canonicalHome && !isInside(canonicalHome, await canonicalPath(fsImpl, resolved))) {
+    throw new Error(labels.mappingEscapesHome);
+  }
+}
+
+async function atomicWrite(fsImpl, target, content, canonicalHome, labels) {
+  const parent = path.dirname(target);
+  const tempName = `.${path.basename(target)}.${process.pid}.${Date.now()}.${temporaryFileCounter++}.${crypto.randomBytes(8).toString('hex')}.tmp`;
+  let temporary;
+  let handle;
+  try {
+    const canonicalParent = await canonicalPath(fsImpl, parent);
+    if (canonicalHome && !isInside(canonicalHome, canonicalParent)) throw new Error(labels.mappingEscapesHome);
+    // Node has no portable openat/renameat2. Revalidation immediately before
+    // path-based rename bounds the unavoidable ancestor-swap window.
+    temporary = path.join(canonicalParent, tempName);
+    if (typeof fsImpl.open === 'function') {
+      handle = await fsImpl.open(temporary, 'wx', 0o600);
+      await handle.writeFile(content, 'utf8');
+      await handle.close();
+      handle = undefined;
+    } else {
+      await fsImpl.writeFile(temporary, content, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    }
+    await assertSafePath(fsImpl, temporary, canonicalHome, labels, false);
+    if (await canonicalPath(fsImpl, temporary) !== temporary) throw new Error(labels.temporaryPathChanged);
+    await assertSafePath(fsImpl, target, canonicalHome, labels, true);
+    await revalidateCanonicalTarget(fsImpl, { target, parent: canonicalParent, home: canonicalHome }, target, canonicalHome, labels);
+    await fsImpl.rename(temporary, target);
+  } finally {
+    if (handle) { try { await handle.close(); } catch { /* best effort close */ } }
+    try {
+      if (temporary && typeof fsImpl.rm === 'function') await fsImpl.rm(temporary, { force: true });
+      else if (temporary && typeof fsImpl.unlink === 'function') await fsImpl.unlink(temporary);
+    } catch { /* preserve typed write failure */ }
+  }
+}
+
+function createSecureFileDriver({
+  platform,
+  capability,
+  manifest = {},
+  fsImpl = fs,
+  labels,
+  resolveTarget,
+  deserialize = value => value,
+  serialize = value => value,
+  validateWrite = () => {}
+} = {}) {
+  const read = async () => {
+    try {
+      const target = resolveTarget(manifest);
+      return deserialize(await readFileByDescriptor(fsImpl, target, manifest.paths && manifest.paths.home, labels));
+    } catch (error) {
+      return createFailure({ platform, capability, operation: 'read', error });
+    }
+  };
+
+  const write = async value => {
+    try {
+      const target = resolveTarget(manifest);
+      validateWrite(value);
+      const encoded = serialize(value);
+      if (typeof encoded !== 'string') throw new Error(labels.serializedValueMustBeString);
+      const home = manifest.paths && manifest.paths.home;
+      const initial = await createCanonicalTarget(fsImpl, target, home, labels, true);
+      await ensureDirectory(fsImpl, initial.parent, initial.home, labels);
+      const canonical = await createCanonicalTarget(fsImpl, target, home, labels, true);
+      await atomicWrite(fsImpl, canonical.target, encoded, canonical.home, labels);
+      return { status: 'ok', platform, capability, operation: 'write', target };
+    } catch (error) {
+      return createFailure({ platform, capability, operation: 'write', error });
+    }
+  };
+
+  const remove = async () => {
+    try {
+      const target = resolveTarget(manifest);
+      const home = manifest.paths && manifest.paths.home;
+      const canonical = await createCanonicalTarget(fsImpl, target, home, labels, true);
+      await revalidateCanonicalTarget(fsImpl, canonical, target, home, labels);
+      await fsImpl.rm(canonical.target, { force: true });
+      return { status: 'ok', platform, capability, operation: 'remove', target };
+    } catch (error) {
+      return createFailure({ platform, capability, operation: 'remove', error });
+    }
+  };
+
+  return { platform, capability, read, write, remove };
+}
+
+module.exports = {
+  createSecureFileDriver,
+  // exported for focused internal reuse if needed by future secure drivers/tests
+  _test: {
+    createFailure,
+    isInside,
+    canonicalPath,
+    assertSafePath,
+    createCanonicalTarget,
+    revalidateCanonicalTarget,
+    readFileByDescriptor,
+    ensureDirectory,
+    atomicWrite
+  }
+};

package/src/platforms/drivers/unsupported.js

@@ -0,0 +1,7 @@
+'use strict';
+
+function createUnsupportedDriver({ platform, capability } = {}) {
+  return { status: 'unsupported', platform, capability };
+}
+
+module.exports = { createUnsupportedDriver };

package/src/platforms/manifest-schema.js

@@ -0,0 +1,398 @@
+'use strict';
+
+const Ajv = require('ajv');
+
+const { hasRequestCodec, hasResponseCodec } = require('../server/api/platform-api-config');
+
+const DRIVER_IDS = new Set([
+  'unsupported',
+  'generic-jsonl',
+  'generic-filesystem',
+  'generic-openai-compatible',
+  'generic-mcp',
+  'generic-prompt',
+  'legacy:claude',
+  'legacy:codex',
+  'legacy:gemini',
+  'legacy:opencode',
+  'legacy:omp',
+  'opencode-conversion',
+  'claude-health'
+]);
+
+const PATH_RESOLVER_IDS = new Set([
+  'declarative',
+  'claude',
+  'codex',
+  'gemini',
+  'opencode',
+  'omp'
+]);
+
+const API_ROUTE_DESCRIPTOR_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['path', 'method', 'capability', 'operation', 'request', 'response'],
+  properties: {
+    path: { type: 'string', pattern: '^/(?:[a-zA-Z0-9_-]+|:[a-zA-Z][a-zA-Z0-9_]*)(?:/(?:[a-zA-Z0-9_-]+|:[a-zA-Z][a-zA-Z0-9_]*))*$' },
+    method: { enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] },
+    capability: { type: 'string', pattern: '^[a-zA-Z][a-zA-Z0-9_-]*$' },
+    operation: { type: 'string', pattern: '^[a-zA-Z][a-zA-Z0-9_-]*$' },
+    request: {},
+    response: {}
+  }
+};
+
+const API_ROUTE_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+
+const CAPABILITY_OPERATIONS = Object.freeze({
+  api: new Set(['getConfig', 'getConfigAuthProviders', 'getConfigCapabilities', 'getConfigResources']),
+  channels: new Set(['applyToSettings', 'bestForRestore', 'catalogMetadata', 'create', 'current', 'enabled', 'getAuth', 'getAuthQuota', 'list', 'models', 'order', 'poolStatus', 'probeModels', 'remove', 'resetHealth', 'speedTest', 'speedTestAll', 'sync', 'syncLocalAuth', 'update']),
+  health: new Set(['healthCheck']),
+  hooks: new Set(['getHooks', 'saveHooks', 'testHooks']),
+  projects: new Set(['createProject', 'deleteProject', 'listProjects', 'saveProjectOrder']),
+  sessions: new Set(['batchDelete', 'createSession', 'delete', 'fork', 'launch', 'listSessions', 'messages', 'outline', 'recent', 'saveSessionOrder', 'search', 'searchAcrossProjects', 'status']),
+  proxy: new Set(['clearLogs', 'start', 'status', 'stop']),
+  conversion: new Set(['convert', 'formats']),
+  statistics: new Set(['daily', 'summary', 'today'])
+});
+
+
+const schema = {
+  type: 'object',
+  required: ['key', 'label', 'command', 'capabilities'],
+  additionalProperties: false,
+  properties: {
+    key: { type: 'string', pattern: '^[a-z0-9][a-z0-9_-]*$' },
+    label: { type: 'string', minLength: 1 },
+    title: { type: 'string', minLength: 1 },
+    command: { type: 'string', minLength: 1 },
+    iconToken: { type: 'string', minLength: 1 },
+    color: { type: 'string' },
+    defaultVisible: { type: 'boolean' },
+    defaultEnabled: { type: 'boolean' },
+    sortOrder: { type: 'integer' },
+    custom: { type: 'boolean' },
+    helpLabel: { type: 'string', minLength: 1 },
+    terminalColor: { type: 'string', minLength: 1 },
+    cliSelectable: { type: 'boolean' },
+    portLabel: { type: 'string', minLength: 1 },
+    apiBasePath: { type: 'string', minLength: 1 },
+    logFile: { type: 'string', minLength: 1 },
+    logAliases: { type: 'array', items: { type: 'string', minLength: 1 } },
+    logNote: { type: 'string' },
+    logColor: { type: 'string', minLength: 1 },
+    portKey: { type: 'string', minLength: 1 },
+    defaultPort: { type: 'integer', minimum: 1 },
+    proxyMode: { enum: ['standard', 'managed'] },
+    proxyLabels: { type: 'object', additionalProperties: { type: 'string' } },
+    modelConfig: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        catalogKey: { type: 'string', pattern: '^[a-z0-9][a-z0-9_-]*$' }
+      }
+    },
+    agentCapabilities: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        projectScope: { type: 'boolean' },
+        repoOperations: { type: 'boolean' }
+      }
+    },
+    resourceTypes: { type: 'object', additionalProperties: { type: 'boolean' } },
+    skillActivation: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['user', 'project'],
+      properties: {
+        user: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['mode', 'format'],
+          properties: {
+            mode: { enum: ['native-copy', 'native-filter', 'unsupported'] },
+            format: { anyOf: [{ type: 'null' }, { type: 'string', pattern: '^[a-z][a-z0-9-]*-skill-v[0-9]+$' }] }
+          }
+        },
+        project: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['mode', 'format'],
+          properties: {
+            mode: { enum: ['native-copy', 'native-filter', 'unsupported'] },
+            format: { anyOf: [{ type: 'null' }, { type: 'string', pattern: '^[a-z][a-z0-9-]*-skill-v[0-9]+$' }] }
+          }
+        }
+      }
+    },
+    auth: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        modes: {
+          type: 'array',
+          minItems: 1,
+          uniqueItems: true,
+          items: { enum: ['api_key', 'oauth', 'none'] }
+        },
+        oauth: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['adapter', 'policy'],
+          properties: {
+            adapter: { type: 'string', pattern: '^[a-z][a-z0-9_-]*$' },
+            policy: { enum: ['single-enabled', 'mixed'] },
+            quota: { type: 'string', pattern: '^[a-z][a-z0-9_-]*$' }
+          }
+        }
+      }
+    },
+    promptFile: { type: ['string', 'null'] },
+    promptLabel: { type: 'string', minLength: 1 },
+    mcpFormat: { enum: ['json'] },
+    statisticsPath: { type: 'string', minLength: 1 },
+    paths: { type: 'object', additionalProperties: { type: 'string' } },
+    pathResolverId: { enum: [...PATH_RESOLVER_IDS] },
+    sessionMapping: { type: 'object', additionalProperties: { type: 'string' } },
+    sessionGlob: { type: 'string', minLength: 1 },
+    resourceMappings: { type: 'object', additionalProperties: { type: 'string' } },
+    projectResources: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['instruction', 'skills', 'mcp'],
+      properties: {
+        instruction: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['path'],
+          properties: {
+            path: { type: ['string', 'null'] }
+          }
+        },
+        skills: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['canonicalRoot', 'readRoots'],
+          properties: {
+            canonicalRoot: { type: 'string', minLength: 1 },
+            readRoots: {
+              type: 'array',
+              minItems: 1,
+              items: { type: 'string', minLength: 1 }
+            }
+          }
+        },
+        agents: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['canonicalRoot'],
+          properties: {
+            canonicalRoot: { type: ['string', 'null'] }
+          }
+        },
+        commands: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['canonicalRoot', 'format'],
+          properties: {
+            canonicalRoot: { type: ['string', 'null'] },
+            format: { type: 'string', minLength: 1 }
+          }
+        },
+        plugins: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['path'],
+          properties: {
+            path: { type: ['string', 'null'] },
+            format: { type: 'string', minLength: 1 }
+          }
+        },
+        mcp: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['path', 'format'],
+          properties: {
+            path: { type: ['string', 'null'] },
+            format: { enum: ['none', 'claude-json', 'codex-toml', 'gemini-json', 'opencode-json', 'omp-json'] }
+          }
+        }
+      },
+    },
+    api: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['prefix'],
+      properties: {
+        prefix: { type: 'string', pattern: '^[a-z0-9][a-z0-9_-]*$' },
+        rootAlias: { type: 'boolean' },
+        rootAliasPaths: {
+          type: 'array',
+          items: { type: 'string', pattern: '^[a-z][a-z0-9_-]*$' }
+        },
+        routes: {
+          type: 'array',
+          items: API_ROUTE_DESCRIPTOR_SCHEMA
+        }
+      }
+    },
+    capabilities: { type: 'object', additionalProperties: { enum: [...DRIVER_IDS] } }
+  }
+};
+
+const validate = new Ajv({ allErrors: true, strict: false }).compile(schema);
+
+function isSafeRelativePath(value) {
+  if (typeof value !== 'string' || !value.trim()) return false;
+  const raw = value.trim().replace(/\\/g, '/');
+  if (raw.startsWith('/') || /^[a-zA-Z]:\//.test(raw) || raw.includes('\0')) return false;
+  const normalized = raw.replace(/^(\.\/)+/, '');
+  const segments = normalized.split('/');
+  return segments.every(segment => segment && segment !== '..');
+}
+
+function validateProjectResources(manifest, errors) {
+  const resources = manifest?.projectResources;
+  if (!resources) return;
+
+  const instructionPath = resources.instruction?.path;
+  if (instructionPath !== null && !isSafeRelativePath(instructionPath)) {
+    errors.push({ instancePath: '/projectResources/instruction/path', message: 'must be a safe relative path or null' });
+  }
+
+  const skills = resources.skills;
+  if (skills && !isSafeRelativePath(skills.canonicalRoot)) {
+    errors.push({ instancePath: '/projectResources/skills/canonicalRoot', message: 'must be a safe relative path' });
+  }
+  for (const [index, root] of (skills?.readRoots || []).entries()) {
+    if (!isSafeRelativePath(root)) {
+      errors.push({ instancePath: `/projectResources/skills/readRoots/${index}`, message: 'must be a safe relative path' });
+    }
+  }
+
+  for (const resourceType of ['agents', 'commands']) {
+    const root = resources[resourceType]?.canonicalRoot;
+    if (root !== null && root !== undefined && !isSafeRelativePath(root)) {
+      errors.push({ instancePath: `/projectResources/${resourceType}/canonicalRoot`, message: 'must be a safe relative path or null' });
+    }
+  }
+
+  const pluginPath = resources.plugins?.path;
+  if (pluginPath !== null && pluginPath !== undefined && !isSafeRelativePath(pluginPath)) {
+    errors.push({ instancePath: '/projectResources/plugins/path', message: 'must be a safe relative path or null' });
+  }
+
+  const mcpPath = resources.mcp?.path;
+  if (mcpPath !== null && !isSafeRelativePath(mcpPath)) {
+    errors.push({ instancePath: '/projectResources/mcp/path', message: 'must be a safe relative path or null' });
+  }
+  if (mcpPath === null && resources.mcp?.format !== 'none') {
+    errors.push({ instancePath: '/projectResources/mcp/format', message: 'must be none when mcp path is null' });
+  }
+}
+
+function validateApiRoutes(manifest, errors) {
+  const api = manifest?.api;
+  if (!api?.routes) return;
+
+  const seen = new Set();
+  const firstSegments = new Set();
+  for (const [index, route] of api.routes.entries()) {
+    if (!route || typeof route !== 'object') continue;
+    const key = `${route.method} ${route.path}`;
+    if (seen.has(key)) {
+      errors.push({ instancePath: `/api/routes/${index}`, message: 'must not duplicate method and path' });
+    }
+    seen.add(key);
+
+    const [firstSegment] = String(route.path || '').split('/').filter(Boolean);
+    if (firstSegment && !firstSegment.startsWith(':')) firstSegments.add(firstSegment);
+    if (!API_ROUTE_METHODS.has(route.method)) continue;
+    if (!manifest.capabilities || !Object.prototype.hasOwnProperty.call(manifest.capabilities, route.capability)) {
+      errors.push({
+        instancePath: `/api/routes/${index}/capability`,
+        message: 'must reference a declared capability'
+      });
+    }
+    const operations = CAPABILITY_OPERATIONS[route.capability];
+    if (!operations || !operations.has(route.operation)) {
+      errors.push({
+        instancePath: `/api/routes/${index}/operation`,
+        message: `must be a supported operation for capability ${route.capability}`
+      });
+    }
+    if (!hasRequestCodec(route.request)) {
+      errors.push({
+        instancePath: `/api/routes/${index}/request`,
+        message: 'must reference a known request codec'
+      });
+    }
+    if (!hasResponseCodec(route.response)) {
+      errors.push({
+        instancePath: `/api/routes/${index}/response`,
+        message: 'must reference a known response codec'
+      });
+    }
+  }
+
+  for (const [index, alias] of (api.rootAliasPaths || []).entries()) {
+    if (!firstSegments.has(alias)) {
+      errors.push({
+        instancePath: `/api/rootAliasPaths/${index}`,
+        message: 'must reference a declared route path'
+      });
+    }
+  }
+}
+
+function validateManifest(manifest) {
+  const valid = validate(manifest);
+  const errors = valid ? [] : (validate.errors || []).slice();
+  const allowed = {
+    'generic-jsonl': new Set(['sessions']),
+    'generic-filesystem': new Set(['resourceSync']),
+    'generic-openai-compatible': new Set(['channels']),
+    'generic-mcp': new Set(['mcp']),
+    'generic-prompt': new Set(['prompts'])
+  };
+
+  for (const [capability, driver] of Object.entries(manifest && manifest.capabilities || {})) {
+    if (allowed[driver] && !allowed[driver].has(capability)) {
+      errors.push({
+        instancePath: `/capabilities/${capability}`,
+        message: `${driver} only supports ${[...allowed[driver]].join(', ')}`
+      });
+    }
+    if (driver === 'generic-mcp') {
+      if (manifest.mcpFormat !== 'json') {
+        errors.push({ instancePath: '/mcpFormat', message: 'generic-mcp requires mcpFormat json' });
+      }
+      if (typeof manifest.resourceMappings?.mcp !== 'string' || !manifest.resourceMappings.mcp.trim()) {
+        errors.push({ instancePath: '/resourceMappings/mcp', message: 'generic-mcp requires a non-empty resourceMappings.mcp' });
+      }
+    }
+    if (driver === 'generic-prompt' && !(
+      (typeof manifest.resourceMappings?.prompts === 'string' && manifest.resourceMappings.prompts.trim()) ||
+      (typeof manifest.promptFile === 'string' && manifest.promptFile.trim())
+    )) {
+      errors.push({
+        instancePath: '/resourceMappings/prompts',
+        message: 'generic-prompt requires a non-empty resourceMappings.prompts or promptFile'
+      });
+    }
+  }
+
+  validateApiRoutes(manifest, errors);
+  return { valid: errors.length === 0, errors };
+}
+
+function normalizeManifestError(errors = []) {
+  return errors.map(error => {
+    const property = error.params && error.params.additionalProperty ? ` ${error.params.additionalProperty}` : '';
+    return `${error.instancePath || error.dataPath || '/'}${property} ${error.message}`;
+  }).join('; ');
+}
+
+module.exports = { DRIVER_IDS, PATH_RESOLVER_IDS, CAPABILITY_OPERATIONS, schema, validateManifest, normalizeManifestError };