@aiwg/cli 2026.10.0 → 2026.10.3

package/dist/src/mcp/config-file.mjs

@@ -0,0 +1,279 @@
+import { urlCarriesUserinfo, credentialLikeArgs, credentialLikeQueryParams, credentialLikeFragmentParams, isCredentialReferenceValue } from './credentials.mjs';
+import { access, lstat, mkdir, open, readFile, realpath, rename, unlink } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { getMcpInjectionDefinition, resolveMcpConfigPath } from '../providers/provider-definitions.mjs';
+
+export async function assertNoSymlinkParents(file, configRoot = dirname(resolve(file))) {
+  const root = resolve(configRoot);
+  const rel = relative(root, resolve(file));
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`MCP config ${file} must be beneath the config directory ${root}`);
+  }
+  let parent = dirname(resolve(file));
+  while (parent !== root) {
+    try {
+      if ((await lstat(parent)).isSymbolicLink()) {
+        throw new Error(`Refusing to write MCP config ${file}: parent directory is a symlink`);
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    parent = dirname(parent);
+  }
+}
+
+export async function assertConfigDestination(file, projectRoot) {
+  if (projectRoot) {
+    const root = resolve(projectRoot);
+    const rel = relative(root, resolve(file));
+    if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+      throw new Error(`MCP config ${file} must be beneath the project directory`);
+    }
+    let current = root;
+    for (const component of rel.split(sep).slice(0, -1)) {
+      current = resolve(current, component);
+      try {
+        if ((await lstat(current)).isSymbolicLink()) {
+          throw new Error(`Refusing to write MCP config ${file}: parent directory is a symlink`);
+        }
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+    }
+  }
+  try {
+    const info = await lstat(file);
+    if (info.isSymbolicLink()) throw new Error(`Refusing to write MCP config ${file}: destination is a symlink`);
+    return info;
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export function isUserMcpScope(provider, scope) {
+  return scope === 'user' || getMcpInjectionDefinition(provider)?.configPath.scope === 'home';
+}
+
+/** True when the resolved destination lives inside the project directory. */
+export function isPathInsideDir(file, dir) {
+  const root = resolve(dir);
+  const rel = relative(root, resolve(file));
+  return Boolean(rel) && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+/**
+ * Refuse a `--scope user` request the provider cannot honour: when the
+ * resolved destination is still the project file, the request would silently
+ * write secrets to a shareable location. Providers whose destination is
+ * genuinely outside the project (home configs, explicit user paths) pass.
+ */
+export function assertSupportedScope(provider, scope, configPath, projectDir = '.') {
+  if (scope !== 'user') return;
+  if (!isPathInsideDir(configPath, projectDir)) return;
+  throw new Error(`Provider "${provider}" has no user-scope destination: --scope user would still write the project file ${configPath}. Use --scope project with --header-env/--env-from references instead of literal credentials.`);
+}
+
+/**
+ * The single place every MCP config writer - `inject`, `install`, and OMP's
+ * `install`/`uninject` - decides whether a destination is a project write.
+ * The decision follows the RESOLVED destination, never the requested scope
+ * string and never a provider's home-directory override (e.g.
+ * `PI_CODING_AGENT_DIR`, `CODEX_HOME`, `GROK_HOME`): a destination that still
+ * resolves inside the project directory gets project containment rules
+ * (ancestor-symlink checks, literal-credential refusal) regardless of what
+ * scope was requested or which environment variable produced the path.
+ * `userScope: true` from this function means the destination is genuinely
+ * outside the project; callers must never override it with a flag of their
+ * own, and must never derive it from `scope` again downstream.
+ *
+ * Throws via `assertSupportedScope` when `--scope user` was requested but the
+ * destination is still inside the project (no private destination exists).
+ */
+export function classifyMcpDestination(provider, scope, configPath, projectDir = '.') {
+  assertSupportedScope(provider, scope, configPath, projectDir);
+  const inProject = isPathInsideDir(configPath, projectDir);
+  return { userScope: !inProject, projectRoot: inProject ? projectDir : undefined };
+}
+
+/**
+ * Remediation for a project-scope literal refusal that names the provider's
+ * real private destination when it has one, instead of always naming
+ * ~/.claude.json. Providers without a user-scope destination get reference
+ * guidance instead.
+ */
+export function projectCredentialRemedy(provider, projectDir = '.') {
+  try {
+    const userPath = resolveMcpConfigPath(provider, projectDir, { scope: 'user' });
+    const projectPath = resolveMcpConfigPath(provider, projectDir, { scope: 'project' });
+    if (userPath && userPath !== projectPath && !isPathInsideDir(userPath, projectDir)) {
+      return `Use --scope user to write private ${userPath} instead, or move secrets into environment variables with --header-env/--env-from references.`;
+    }
+  } catch {
+    // An unresolvable user destination means references are the only remedy.
+  }
+  return `Move secrets into environment variables with --header-env/--env-from references instead; --scope user has no private destination for provider "${provider}".`;
+}
+
+/** Reject non-string env/headers values with a schema-style error. */
+function assertStringMap(server, field) {
+  const entries = server[field];
+  if (entries === undefined || entries === null) return {};
+  if (typeof entries !== 'object' || Array.isArray(entries)) {
+    throw new Error(`Invalid MCP server "${server.name}": ${field} must be an object`);
+  }
+  for (const [key, value] of Object.entries(entries)) {
+    if (typeof value !== 'string') {
+      throw new Error(`Invalid MCP server "${server.name}": ${field}["${key}"] must be a string`);
+    }
+  }
+  return entries;
+}
+
+export function assertProjectCredentials(servers, configPath, remedy) {
+  const literals = servers.flatMap(server => {
+    const reasons = [];
+    // A value is shareable only when it is empty or a supported reference
+    // form (${VAR}, ${env:VAR}, {env:VAR}); any other string is a literal.
+    for (const field of ['env', 'headers']) {
+      const entries = assertStringMap(server, field);
+      const literalKeys = Object.entries(entries)
+        .filter(([, value]) => value !== '' && !isCredentialReferenceValue(value))
+        .map(([key]) => key);
+      if (literalKeys.length) reasons.push(`${server.name} has literal ${field} values (${literalKeys.join(', ')})`);
+    }
+    // OMP persists auth/oauth beside env/headers, so the same refusal covers
+    // any secret-bearing value there; `type` alone selects a flow, not a secret.
+    // This deliberately includes all URL fields (tokenUrl/redirectUri/resource),
+    // so OAuth query and fragment credentials cannot bypass project protection.
+    for (const field of ['auth', 'oauth']) {
+      const section = server[field];
+      if (section !== undefined && section !== null) {
+        if (typeof section !== 'object' || Array.isArray(section)) {
+          throw new Error(`Invalid MCP server "${server.name}": ${field} must be an object`);
+        }
+        const literalKeys = Object.keys(section).filter(key =>
+          key !== 'type' && section[key] !== '' && section[key] !== undefined && section[key] !== null);
+        if (literalKeys.length) reasons.push(`${server.name} has literal ${field} values (${literalKeys.join(', ')})`);
+      }
+    }
+    if (urlCarriesUserinfo(server.url)) reasons.push(`${server.name} has URL userinfo`);
+    if (credentialLikeQueryParams(server.url).length) reasons.push(`${server.name} has URL query credentials`);
+    if (credentialLikeFragmentParams(server.url).length) reasons.push(`${server.name} has URL fragment credentials`);
+    // A flag like --token=... or --password <value> almost always carries the secret
+    // in argv, visible to every process listing on the host; the same literal-credential
+    // refusal that applies to env/headers applies here for a shareable project file.
+    // Name only the flag, never the "--flag=value" form's value half.
+    const argFlags = credentialLikeArgs(server.args).map(arg =>
+      /^--?[A-Za-z][A-Za-z0-9_-]*(?=[ =]|$)/.exec(arg)?.[0] || '[redacted]');
+    if (argFlags.length) reasons.push(`${server.name} has credential-like args (${argFlags.join(', ')})`);
+    return reasons;
+  });
+  if (literals.length) {
+    throw new Error(`Refusing to write project MCP config ${configPath}: ${literals.join('; ')}. ${remedy || 'Use --scope user to write to a private destination instead.'}`);
+  }
+}
+
+export function assertConfigObject(config, serversKey) {
+  const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (!isObject(config) || (Object.hasOwn(config, serversKey) && !isObject(config[serversKey]))) {
+    throw new Error('MCP configuration must contain an object root and an object server map');
+  }
+}
+
+export async function writeConfigAtomic(file, content, { userScope = false, projectRoot, newFileMode, mode: restoreMode, rejectSymlinkParents = false, symlinkRoot } = {}) {
+  if (rejectSymlinkParents) await assertNoSymlinkParents(file, symlinkRoot);
+  const info = await assertConfigDestination(file, projectRoot);
+  const mode = restoreMode ?? (userScope ? 0o600 : info ? info.mode & 0o7777 : newFileMode ?? 0o666);
+  await mkdir(dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  let handle;
+  try {
+    handle = await open(temporary, 'wx', mode);
+    await handle.writeFile(content, 'utf-8');
+    if (userScope || info || restoreMode !== undefined || newFileMode !== undefined) await handle.chmod(mode);
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    if (rejectSymlinkParents) await assertNoSymlinkParents(file, symlinkRoot);
+    await assertConfigDestination(file, projectRoot);
+    await rename(temporary, file);
+  } finally {
+    try {
+      if (handle) await handle.close();
+    } finally {
+      await unlink(temporary).catch(() => {});
+    }
+  }
+}
+
+/** Resolve existing parent aliases without creating directories during a dry run. */
+export async function canonicalConfigPath(file) {
+  let parent = dirname(resolve(file));
+  const missing = [];
+  while (true) {
+    try {
+      return resolve(await realpath(parent), ...missing, basename(file));
+    } catch (error) {
+      if (error.code !== 'ENOENT' || dirname(parent) === parent) throw error;
+      missing.unshift(basename(parent));
+      parent = dirname(parent);
+    }
+  }
+}
+
+/** Check the destination and the nearest existing parent before a multi-file write. */
+export async function prepareConfigWrite(file, options = {}) {
+  await assertConfigDestination(file, options.projectRoot);
+  let parent = dirname(resolve(file));
+  while (true) {
+    try {
+      // Follow a root/home alias, just as assertConfigDestination does.
+      const actual = await realpath(parent);
+      if (!(await lstat(actual)).isDirectory()) throw new Error(`Config parent ${parent} must be a directory`);
+      await access(actual, constants.W_OK | constants.X_OK);
+      return;
+    } catch (error) {
+      if (error.code !== 'ENOENT' || dirname(parent) === parent) {
+        throw new Error(`Cannot prepare config destination ${file}: ${error.message}`);
+      }
+      parent = dirname(parent);
+    }
+  }
+}
+
+/** Write MCP, settings and ownership in the supplied order, restoring earlier files on failure. */
+export async function writeConfigTransaction(writes) {
+  const originals = [];
+  for (const { file, options = {} } of writes) {
+    await prepareConfigWrite(file, options);
+    const info = await assertConfigDestination(file, options.projectRoot);
+    originals.push(info ? { content: await readFile(file), mode: info.mode & 0o7777 } : null);
+  }
+  let completed = 0;
+  try {
+    for (const { file, content, options } of writes) {
+      await writeConfigAtomic(file, content, options);
+      completed++;
+    }
+  } catch (error) {
+    const failures = [];
+    for (let index = completed - 1; index >= 0; index--) {
+      const { file, options = {} } = writes[index];
+      try {
+        if (originals[index]) {
+          await writeConfigAtomic(file, originals[index].content, { ...options, mode: originals[index].mode });
+        } else {
+          await assertConfigDestination(file, options.projectRoot);
+          await unlink(file);
+        }
+      } catch (rollbackError) {
+        failures.push(`${file}: ${rollbackError.message}`);
+      }
+    }
+    if (failures.length) throw new Error(`${error.message}; config rollback failed: ${failures.join('; ')}`);
+    throw error;
+  }
+}

package/dist/src/mcp/config-layers.mjs

@@ -0,0 +1,348 @@
+/**
+ * Layered MCP configuration roots.
+ *
+ * AIWG_CONFIG_LAYERS lists configuration directories separated by the
+ * platform path delimiter (`:` on POSIX, `;` on Windows), lowest precedence
+ * first. Each directory may hold mcp-servers.json and mcp-profiles.json. An
+ * entry (server or profile) in a later directory replaces the entry of the
+ * same name in an earlier one; entries are not merged field by field.
+ *
+ * The last directory is the write layer: add, update and recordInjection
+ * write there, and nothing from an earlier layer is copied into it unless
+ * that entry is updated.
+ *
+ * When AIWG_CONFIG_LAYERS is unset, or a registry is constructed with an
+ * explicit directory, the single-directory behaviour applies unchanged.
+ */
+
+import { lstat, mkdtemp, readFile, readlink, realpath, rmdir } from 'fs/promises';
+import { basename, dirname, isAbsolute, posix, relative, resolve, sep, win32 } from 'path';
+import { assertConfigDestination, assertNoSymlinkParents, writeConfigAtomic } from './config-file.mjs';
+import { resolveCredentialPolicy, stricterCredentialPolicy, warnCredentialPolicyRelaxation, warnDroppedOverlayPolicy } from './credentials.mjs';
+
+/**
+ * `platform` lets tests validate Windows path semantics (`C:\org`, UNC
+ * `\\server`, root-relative `\org`/`/org`) deterministically on any host; it
+ * defaults to the real host platform, so production calls behave exactly as
+ * the native `path` module already would.
+ */
+export function resolveConfigLayers(configDirOverride, env = process.env, { platform = process.platform } = {}) {
+  if (configDirOverride) return null;
+  const raw = env.AIWG_CONFIG_LAYERS;
+  if (!raw || !raw.trim()) return null;
+  const pathForPlatform = platform === 'win32' ? win32 : posix;
+  // A Windows-formatted value uses `;`; splitting a drive-qualified entry
+  // (`C:\org`) on the real host's POSIX `:` would wrongly cut it at the drive
+  // letter, so the simulated platform's own delimiter is used, not the real
+  // host's - matching the native `path` module's behaviour when the real host
+  // actually is that platform.
+  const entries = raw.split(pathForPlatform.delimiter).map(entry => entry.trim()).filter(Boolean);
+  // A bare leading `\` or `/` with no drive letter is current-drive-relative
+  // under Windows path semantics: resolving it from C:\work versus D:\work
+  // selects different drives, so a layer list could change meaning across
+  // hosts. The backslash form is refused on every platform, since it is never
+  // a valid POSIX absolute path either. The forward-slash form is refused
+  // only when interpreting entries under actual Windows path semantics; on
+  // POSIX, a leading `/` is an unambiguous, fully-qualified absolute path and
+  // must keep working. Drive-qualified (`C:\`, `C:/`) and UNC (`\\server`,
+  // `//server`) forms remain allowed on every platform.
+  const driveRelativePattern = platform === 'win32' ? /^[\\/](?![\\/])/ : /^\\(?!\\)/;
+  const driveRelativeEntries = entries.filter(entry => driveRelativePattern.test(entry));
+  if (driveRelativeEntries.length) {
+    throw new Error(`AIWG_CONFIG_LAYERS entries must be absolute paths; refusing Windows current-drive-relative entries: ${driveRelativeEntries.join(', ')}`);
+  }
+  // A relative entry would resolve against the current working directory, so the
+  // same AIWG_CONFIG_LAYERS value would name different layers from different
+  // invocation directories. Refuse instead of silently picking a directory.
+  const relativeEntries = entries.filter(entry => !pathForPlatform.isAbsolute(entry));
+  if (relativeEntries.length) {
+    throw new Error(`AIWG_CONFIG_LAYERS entries must be absolute paths; refusing relative entries: ${relativeEntries.join(', ')}`);
+  }
+  const layers = entries.map(entry => pathForPlatform.resolve(entry));
+  return layers.length > 0 ? layers : null;
+}
+
+async function readLayer(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf-8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    if (error instanceof SyntaxError) throw new Error(`Invalid JSON in MCP configuration layer ${path}`);
+    throw error;
+  }
+}
+
+/** File-format fields every layer file keeps, whichever layer set them. */
+const FORMAT_FIELDS = ['apiVersion', 'kind'];
+
+/** Bookkeeping fields that do not make an entry "changed" for layering purposes. */
+const BOOKKEEPING_FIELDS = ['injectedProviders', 'addedAt', 'createdAt', 'updatedAt'];
+
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value === null || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map(key => [key, sortKeys(value[key])]));
+}
+
+function comparable(entry) {
+  const copy = { ...entry };
+  for (const field of BOOKKEEPING_FIELDS) delete copy[field];
+  return JSON.stringify(sortKeys(copy));
+}
+
+/**
+ * Read `filename` from every layer and merge the `collection` map by entry
+ * name. Top-level fields come from the highest layer that sets them, except
+ * credentialPolicy: lower (non-write) layers fold together with the
+ * strictest value winning - an enforced organisation floor - and the write
+ * layer's own declared value (a personal default) is then bounded below by
+ * that floor, never copying the floor itself into the write layer's record.
+ * `lowerPolicySource` names the config file of the lower layer that set the
+ * folded floor's value (the first layer to set it; a later layer repeating
+ * the same strictness does not move attribution), for diagnostics.
+ *
+ * Returns the merged data and a layering record: the names defined in the
+ * write layer, and comparable forms of entries and top-level fields in lower layers.
+ */
+export async function loadLayered(layers, filename, collection, defaults) {
+  const merged = { ...defaults, [collection]: {} };
+  const lower = new Map();
+  const own = new Set();
+  const lowerFields = new Map();
+  const ownFields = new Set();
+  let ownPolicy;
+  let lowerPolicy;
+  let lowerPolicySource;
+  const writeLayer = layers.length - 1;
+  for (const [index, dir] of layers.entries()) {
+    const parsed = await readLayer(resolve(dir, filename));
+    if (!parsed) continue;
+    const { [collection]: entries, ...rest } = parsed;
+    if (index === writeLayer) {
+      ownPolicy = rest.credentialPolicy;
+    } else if (Object.hasOwn(rest, 'credentialPolicy')) {
+      try {
+        const folded = stricterCredentialPolicy(lowerPolicy, rest.credentialPolicy);
+        if (folded !== lowerPolicy) lowerPolicySource = resolve(dir, filename);
+        lowerPolicy = folded;
+      } catch (error) {
+        throw new Error(`Invalid MCP credential policy in layer ${resolve(dir, filename)}: ${error.message}`);
+      }
+    }
+    Object.assign(merged, rest);
+    // Across several lower layers, credentialPolicy folds by strictness, not
+    // by "last layer wins" like every other field: keep the running snapshot
+    // in sync with the folded floor so a later lowerFields comparison (used
+    // to decide whether to copy an unchanged inherited value) reflects it,
+    // not one lower layer's own raw declared value.
+    if (index < writeLayer) merged.credentialPolicy = lowerPolicy;
+    for (const field of Object.keys(rest)) {
+      if (index === writeLayer) ownFields.add(field);
+      else lowerFields.set(field, comparable({ value: merged[field] }));
+    }
+    for (const [name, entry] of Object.entries(entries || {})) {
+      merged[collection][name] = entry;
+      if (index === writeLayer) own.add(name);
+      else lower.set(name, comparable(entry));
+    }
+  }
+  // No layer declared a policy anywhere: leave the field absent, exactly as
+  // when `defaults` carries no credentialPolicy, rather than materializing
+  // the built-in `literal` default as a stored value.
+  let effectivePolicy;
+  if (ownPolicy !== undefined || lowerPolicy !== undefined) {
+    try {
+      effectivePolicy = resolveCredentialPolicy({
+        registryPolicy: ownPolicy, floorPolicy: lowerPolicy, floorSource: lowerPolicySource, env: {},
+      });
+    } catch (error) {
+      throw new Error(`Invalid MCP credential policy in layer ${resolve(layers[writeLayer], filename)}: ${error.message}`);
+    }
+    merged.credentialPolicy = effectivePolicy;
+  } else {
+    delete merged.credentialPolicy;
+  }
+  return { data: merged, layering: { lower, own, lowerFields, ownFields, ownPolicy, lowerPolicy, lowerPolicySource, effectivePolicy } };
+}
+
+/** True when the entry is defined only below the write layer. */
+export function isLowerLayerEntry(layering, name) {
+  return layering.lower.has(name) && !layering.own.has(name);
+}
+
+/**
+ * True when the write layer overrides a lower-layer entry that still carries
+ * worker qualification. Removing that override would silently re-expose the
+ * lower entry's qualification, so removal must be refused instead.
+ */
+export function lowerEntryQualified(layering, name) {
+  if (!layering?.lower?.has(name) || !layering?.own?.has(name)) return false;
+  try {
+    return JSON.parse(layering.lower.get(name))?.workerQualification !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The data to persist in the write layer: entries defined there, new entries,
+ * and lower-layer entries whose content (bookkeeping aside) was changed.
+ * Top-level fields follow the same rule, without entry bookkeeping exclusions;
+ * apiVersion and kind are always kept so the file stays self-describing.
+ */
+export function writeLayerData(data, collection, layering, explicitPolicy = false) {
+  const entries = Object.entries(data[collection] || {}).filter(([name, entry]) =>
+    layering.own.has(name) || !layering.lower.has(name) || comparable(entry) !== layering.lower.get(name));
+  const fields = Object.entries(data).filter(([field, value]) => field !== collection && (
+    FORMAT_FIELDS.includes(field) || layering.ownFields.has(field) || !layering.lowerFields.has(field) ||
+    comparable({ value }) !== layering.lowerFields.get(field)));
+  const persisted = { ...Object.fromEntries(fields), [collection]: Object.fromEntries(entries) };
+  // A setter explicitly writes even when its value equals the merged floor.
+  // Other saves retain policy ownership, without copying an inherited floor.
+  if (explicitPolicy || data.credentialPolicy !== layering.effectivePolicy) {
+    const effective = resolveCredentialPolicy({
+      flag: data.credentialPolicy, floorPolicy: layering.lowerPolicy, floorSource: layering.lowerPolicySource, env: {},
+    });
+    if (effective !== data.credentialPolicy) {
+      const location = layering.lowerPolicySource ? ` (set in ${layering.lowerPolicySource})` : '';
+      throw new Error(`Cannot relax MCP credential policy floor "${effective}"${location} to "${data.credentialPolicy}".`);
+    }
+    persisted.credentialPolicy = data.credentialPolicy;
+  } else if (layering.ownPolicy !== undefined &&
+    resolveCredentialPolicy({ flag: layering.ownPolicy, floorPolicy: layering.lowerPolicy, floorSource: layering.lowerPolicySource, env: {} }) !== layering.ownPolicy) {
+    delete persisted.credentialPolicy;
+    warnDroppedOverlayPolicy(layering.ownPolicy, layering.lowerPolicy, layering.lowerPolicySource);
+  }
+  return persisted;
+}
+
+/** Resolve a target, including a missing suffix, without creating it. */
+async function targetRealpath(path, aliases = []) {
+  const absolute = resolve(path);
+  if (aliases.includes(absolute)) throw new Error(`MCP configuration target symlink cycle: ${[...aliases, absolute].join(' -> ')}`);
+  try {
+    return await realpath(path);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    // Resolve dangling aliases too: creating their missing referent would change
+    // a lower layer even though realpath currently reports ENOENT.
+    if (dirname(absolute) === absolute) throw error;
+    const candidate = resolve(await targetRealpath(dirname(absolute), aliases), basename(absolute));
+    try {
+      if ((await lstat(candidate)).isSymbolicLink()) {
+        return targetRealpath(resolve(dirname(candidate), await readlink(candidate)), [...aliases, absolute]);
+      }
+    } catch (statError) {
+      if (statError.code !== 'ENOENT') throw statError;
+    }
+    return candidate;
+  }
+}
+
+/** Probe the filesystem containing the nearest existing ancestor of a target. */
+export async function isCaseInsensitivePath(path) {
+  let ancestor = resolve(path);
+  while (true) {
+    try {
+      await realpath(ancestor);
+      break;
+    } catch (error) {
+      if (error.code !== 'ENOENT' || dirname(ancestor) === ancestor) throw error;
+      ancestor = dirname(ancestor);
+    }
+  }
+  let probe;
+  try {
+    probe = await mkdtemp(resolve(ancestor, '.aiwg-case-probe-a-'));
+    const alternate = resolve(dirname(probe), basename(probe).toUpperCase());
+    try {
+      const [original, folded] = await Promise.all([lstat(probe), lstat(alternate)]);
+      return original.dev === folded.dev && original.ino === folded.ino;
+    } catch (error) {
+      if (error.code === 'ENOENT') return false;
+      throw error;
+    }
+  } catch (error) {
+    // Read-only ancestors cannot be probed: compare conservatively rather than allow overlap.
+    if (error.code === 'EACCES' || error.code === 'EPERM' || error.code === 'EROFS') return true;
+    throw error;
+  } finally {
+    if (probe) await rmdir(probe);
+  }
+}
+
+function inside(target, parent, caseInsensitive) {
+  const rel = relative(caseInsensitive ? parent.toLowerCase() : parent, caseInsensitive ? target.toLowerCase() : target);
+  return !rel || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+/** Refuse a write that could modify another configuration layer. */
+export async function assertLayerWriteDestination(layers, filename) {
+  const targets = await Promise.all(layers.map(async dir => ({
+    dir: await targetRealpath(dir),
+    files: await Promise.all(['mcp-servers.json', 'mcp-profiles.json'].map(name => targetRealpath(resolve(dir, name)))),
+  })));
+  const write = targets[targets.length - 1];
+  const caseInsensitive = await isCaseInsensitivePath(write.dir);
+  const writeFile = await targetRealpath(resolve(layers[layers.length - 1], filename));
+  for (const lower of targets.slice(0, -1)) {
+    if (inside(write.dir, lower.dir, caseInsensitive) || inside(writeFile, lower.dir, caseInsensitive) || lower.files.some(file => inside(writeFile, file, caseInsensitive))) {
+      throw new Error(`Refusing overlapping MCP configuration layer targets: ${writeFile} overlaps ${lower.dir}`);
+    }
+  }
+  const file = resolve(layers[layers.length - 1], filename);
+  await assertNoSymlinkParents(file, layers[layers.length - 1]);
+  await assertConfigDestination(file);
+}
+
+/** Persist atomically, then refresh ownership only after a successful write. */
+export async function saveLayerData(file, data, collection, layers, layering, explicitPolicy = false) {
+  if (layers) await assertLayerWriteDestination(layers, basename(file));
+  const persisted = layering ? writeLayerData(data, collection, layering, explicitPolicy) : data;
+  // The active identity layer file is always 0600: it is the personal write
+  // layer of an active AIWG_CONFIG_LAYERS configuration and may carry secrets.
+  // Without layering, `file` is whatever single directory the caller
+  // configured (which may be a shared, group-readable organisation checkout
+  // maintained directly, not a private identity directory): an existing file
+  // keeps its mode, while a newly created file starts private at 0600.
+  await writeConfigAtomic(file, JSON.stringify(persisted, null, 2) + '\n', layers
+    ? { userScope: true, rejectSymlinkParents: true }
+    : { newFileMode: 0o600, rejectSymlinkParents: true });
+  if (layering) {
+    layering.own = new Set(Object.keys(persisted[collection] || {}));
+    layering.ownFields = new Set(Object.keys(persisted).filter(field => field !== collection));
+    layering.ownPolicy = persisted.credentialPolicy;
+    layering.effectivePolicy = data.credentialPolicy;
+  }
+}
+
+/**
+ * Resolve a profile's `extends` chain. Servers are concatenated base-first
+ * without duplicates. Per provider key, toolDeny accumulates across the chain
+ * and toolAllow is taken from the most-derived profile that sets it.
+ */
+export function resolveProfileExtends(name, profiles, seen = []) {
+  const profile = profiles[name];
+  if (!profile) {
+    throw new Error(seen.length > 0
+      ? `Profile "${seen[seen.length - 1]}" extends "${name}", which is not defined in any configuration layer.`
+      : `Profile "${name}" not found.`);
+  }
+  if (seen.includes(name)) throw new Error(`Profile extends cycle: ${[...seen, name].join(' -> ')}`);
+  const bases = (profile.extends || []).map(base => resolveProfileExtends(base, profiles, [...seen, name]));
+
+  const servers = [];
+  const providerOverrides = {};
+  for (const source of [...bases, profile]) {
+    for (const server of source.servers || []) if (!servers.includes(server)) servers.push(server);
+    for (const [provider, override] of Object.entries(source.providerOverrides || {})) {
+      const previous = providerOverrides[provider] || {};
+      providerOverrides[provider] = {
+        ...previous,
+        ...(override.toolDeny ? { toolDeny: [...new Set([...(previous.toolDeny || []), ...override.toolDeny])] } : {}),
+        ...(override.toolAllow ? { toolAllow: [...override.toolAllow] } : {}),
+      };
+    }
+  }
+  return { ...profile, servers, providerOverrides };
+}