sneakoscope 6.1.2 → 6.4.0

package/dist/core/mcp-config/mutation.js

@@ -0,0 +1,366 @@
+import { writeCodexConfigGuarded } from '../codex/codex-config-guard.js';
+import { withFileLock } from '../locks/file-lock.js';
+import { createMcpBackup, finalizeMcpBackup } from './backup.js';
+import { CodexMcpCliAdapter } from './codex-cli-adapter.js';
+import { isRecord, privateInlineEnvironment, rawStringArray, readMcpConfigDocument } from './config-reader.js';
+import { removeMcpServerText as removeServerText, renderMcpServerBlock, replaceOrAppendMcpServer, setMcpServerEnabledText as setEnabledText } from './guarded-patch.js';
+import { listMcpInventory } from './inventory.js';
+import { redactMcpError, redactMcpErrorWithSecrets } from './redaction.js';
+import { isOfficialMcpServerName, McpSecretPolicyError, normalizeApprovalMode, normalizeMcpMutationInput, normalizeMcpServerName } from './secret-policy.js';
+import { McpScopeError, resolveMcpScope } from './scope.js';
+import { MCP_MUTATION_SCHEMA } from './types.js';
+export async function addMcpServer(input, scope, options = {}) {
+    let normalized;
+    try {
+        normalized = normalizeMcpMutationInput(input);
+    }
+    catch (error) {
+        return inputFailure('add', null, scope, error);
+    }
+    if (!isOfficialMcpServerName(normalized.name))
+        return failure('add', normalized.name, scope, ['invalid_mcp_server_name_for_codex_cli']);
+    return runMutation('add', normalized.name, scope, options, { input: normalized });
+}
+export async function editMcpServer(nameInput, patch, scope, options = {}) {
+    const name = normalizeMcpServerName(nameInput);
+    if (!name)
+        return failure('edit', null, scope, ['invalid_mcp_server_name']);
+    if (!isRecord(patch))
+        return failure('edit', name, scope, ['mcp_edit_patch_required']);
+    if ('env' in patch)
+        return failure('edit', name, scope, ['mcp_raw_secret_storage_forbidden']);
+    return runMutation('edit', name, scope, options, { patch });
+}
+export async function duplicateMcpServer(sourceInput, newNameInput, scope, options = {}) {
+    const sourceName = normalizeMcpServerName(sourceInput);
+    const newName = normalizeMcpServerName(newNameInput);
+    if (!sourceName || !newName || !isOfficialMcpServerName(newName))
+        return failure('duplicate', newName, scope, ['invalid_mcp_server_name']);
+    return runMutation('duplicate', newName, scope, options, { sourceName });
+}
+export async function setMcpServerEnabled(nameInput, enabled, scope, options = {}) {
+    const name = normalizeMcpServerName(nameInput);
+    if (!name)
+        return failure(enabled ? 'enable' : 'disable', null, scope, ['invalid_mcp_server_name']);
+    return runMutation(enabled ? 'enable' : 'disable', name, scope, options, { enabled });
+}
+export async function removeMcpServer(nameInput, scope, options = {}) {
+    const name = normalizeMcpServerName(nameInput);
+    if (!name)
+        return failure('remove', null, scope, ['invalid_mcp_server_name']);
+    return runMutation('remove', name, scope, options, {});
+}
+const LEGACY_SECRET_ACTION = 'legacy_inline_secret_action';
+const REVIEWED_LEGACY_ENV_KEYS = 'reviewed_legacy_env_keys';
+const SAFE_TRANSFORM_UNSUPPORTED_REASONS = new Set([
+    'codex_cli_not_found',
+    'codex_cli_server_name_unsupported',
+    'codex_cli_mutation_unsupported'
+]);
+async function runMutation(action, name, scope, options, request) {
+    let ref;
+    let sensitiveInlineValues = [];
+    try {
+        ref = await resolveMcpScope(scope, options);
+        if (scope === 'project' && options.confirmProjectMutation !== true)
+            throw new McpScopeError('mcp_project_mutation_confirmation_required');
+    }
+    catch (error) {
+        return failure(action, name, scope, [error instanceof McpScopeError ? error.code : 'mcp_scope_invalid'], redactMcpError(error));
+    }
+    const cli = options.cli ?? new CodexMcpCliAdapter({ ...(options.codexPath ? { codexPath: options.codexPath } : {}) });
+    try {
+        return await withFileLock({ lockPath: `${ref.configPath}.sks-mcp.lock`, timeoutMs: 10_000, staleMs: 60_000 }, async () => {
+            for (let attempt = 1; attempt <= 3; attempt += 1) {
+                const document = await readMcpConfigDocument(ref);
+                sensitiveInlineValues = mergeSensitiveValues(sensitiveInlineValues, inlineEnvironmentStringValues(document.rawServers));
+                const prepared = prepareMutation(action, name, document.rawServers, request);
+                if (!prepared.ok)
+                    return failure(action, name, scope, prepared.blockers, null, attempt);
+                const generated = await generateNextText(cli, document.text, action, name, prepared.input, prepared.legacyEnv, request.enabled, sensitiveInlineValues);
+                if (!generated.ok || generated.text === null) {
+                    return failure(action, name, scope, generated.blockers, generated.publicError, attempt, generated.cliUsed, generated.fallbackUsed);
+                }
+                const backup = await createMcpBackup(ref, document.text, action, name);
+                const write = await writeCodexConfigGuarded({
+                    root: ref.root,
+                    configPath: ref.configPath,
+                    before: document.text,
+                    cause: `mcp-config-${action}`,
+                    backupTag: `mcp-config-${action}`,
+                    ownershipVerified: true,
+                    verifyUnchangedBeforeWrite: true,
+                    expectedBeforeExists: document.exists,
+                    preserveFastUiKeys: false,
+                    preserveTextFormatting: true,
+                    mutate: () => generated.text
+                });
+                if (!write.ok && write.status === 'concurrent_change_detected' && attempt < 3)
+                    continue;
+                if (!write.ok)
+                    return failure(action, name, scope, [`mcp_config_write_${write.status}`], null, attempt, generated.cliUsed, generated.fallbackUsed);
+                let finalized;
+                try {
+                    finalized = await finalizeMcpBackup(backup, generated.text);
+                }
+                catch (error) {
+                    return postWriteReceiptFailure(action, name, scope, write.changed, backup.metadata.id, attempt, generated, error, sensitiveInlineValues);
+                }
+                const inventory = await listMcpInventory(scope, { ...options, cli: safeInventoryCli(cli) });
+                return {
+                    schema: MCP_MUTATION_SCHEMA,
+                    ok: true,
+                    action,
+                    name,
+                    scope,
+                    changed: write.changed,
+                    official_cli_used: generated.cliUsed,
+                    fallback_used: generated.fallbackUsed,
+                    backup_id: finalized.id,
+                    restart_required: write.changed,
+                    servers: inventory.servers,
+                    blockers: [],
+                    warnings: [...new Set(['changes_apply_to_new_codex_sessions', ...generated.warnings])],
+                    attempts: attempt,
+                    public_error: null
+                };
+            }
+            return failure(action, name, scope, ['mcp_config_busy'], null, 3);
+        });
+    }
+    catch (error) {
+        const blocker = messageOf(error).startsWith('file_lock_timeout:') ? 'mcp_config_busy' : 'mcp_mutation_failed';
+        return failure(action, name, scope, [blocker], safeMutationPublicError(error, sensitiveInlineValues, blocker));
+    }
+}
+function prepareMutation(action, name, servers, request) {
+    const existing = servers[name] || null;
+    if (action === 'add' && existing)
+        return { ok: false, blockers: ['mcp_server_already_exists'] };
+    if (action !== 'add' && action !== 'duplicate' && !existing)
+        return { ok: false, blockers: ['mcp_server_not_found'] };
+    if (action === 'remove' || action === 'enable' || action === 'disable')
+        return { ok: true, input: null, legacyEnv: {} };
+    if (action === 'add')
+        return { ok: true, input: request.input || null, legacyEnv: {} };
+    const source = action === 'duplicate' ? servers[request.sourceName || ''] || null : existing;
+    if (!source)
+        return { ok: false, blockers: ['mcp_source_server_not_found'] };
+    const legacyEnv = privateInlineEnvironment(source);
+    if (action === 'duplicate' && isRecord(source.env) && Object.keys(source.env).length) {
+        return { ok: false, blockers: ['mcp_duplicate_legacy_inline_secret_forbidden'] };
+    }
+    const legacyDecision = legacySecretDecision(source, request.patch, legacyEnv);
+    if (!legacyDecision.ok)
+        return legacyDecision;
+    const base = mutationInputFromRaw(action === 'duplicate' ? name : name, source);
+    const patch = action === 'edit' ? withoutLegacySecretControls(request.patch || {}) : {};
+    const merged = action === 'edit' ? { ...base, ...patch, name } : { ...base, name };
+    try {
+        let input = normalizeMcpMutationInput(merged);
+        if (legacyDecision.action === 'move_to_secure_reference') {
+            input = normalizeMcpMutationInput({
+                ...input,
+                env_vars: [...new Set([...(input.env_vars || []), ...legacyDecision.envNames])].sort()
+            });
+        }
+        return {
+            ok: true,
+            input,
+            legacyEnv: legacyDecision.action === 'move_to_secure_reference' ? {} : legacyEnv
+        };
+    }
+    catch (error) {
+        return { ok: false, blockers: error instanceof McpSecretPolicyError ? error.blockers : ['mcp_mutation_input_invalid'] };
+    }
+}
+function legacySecretDecision(source, patch, legacyEnv) {
+    const hasAction = patch ? Object.prototype.hasOwnProperty.call(patch, LEGACY_SECRET_ACTION) : false;
+    const hasReview = patch ? Object.prototype.hasOwnProperty.call(patch, REVIEWED_LEGACY_ENV_KEYS) : false;
+    if (!hasAction && !hasReview)
+        return { ok: true, action: 'leave_unchanged', envNames: [] };
+    const action = patch?.[LEGACY_SECRET_ACTION];
+    if (action === 'leave_unchanged') {
+        return hasReview
+            ? { ok: false, blockers: ['mcp_legacy_secret_review_not_allowed_for_leave_unchanged'] }
+            : { ok: true, action, envNames: [] };
+    }
+    if (action !== 'move_to_secure_reference') {
+        return { ok: false, blockers: ['invalid_mcp_legacy_secret_action'] };
+    }
+    if (typeof source.url === 'string') {
+        return { ok: false, blockers: ['mcp_legacy_secret_migration_requires_stdio'] };
+    }
+    const inline = isRecord(source.env) ? source.env : {};
+    const inlineKeys = Object.keys(inline).sort();
+    if (!inlineKeys.length)
+        return { ok: false, blockers: ['mcp_legacy_inline_secret_not_found'] };
+    const migratableKeys = Object.keys(legacyEnv).sort();
+    if (inlineKeys.length !== migratableKeys.length || inlineKeys.some((key, index) => key !== migratableKeys[index])) {
+        return { ok: false, blockers: ['mcp_legacy_secret_secure_reference_names_unavailable'] };
+    }
+    const reviewed = patch?.[REVIEWED_LEGACY_ENV_KEYS];
+    if (!Array.isArray(reviewed) || reviewed.some((key) => typeof key !== 'string')) {
+        return { ok: false, blockers: ['mcp_legacy_secret_review_required'] };
+    }
+    const reviewedNames = reviewed.map(String);
+    const uniqueReviewed = [...new Set(reviewedNames)].sort();
+    if (reviewedNames.length !== uniqueReviewed.length
+        || uniqueReviewed.length !== migratableKeys.length
+        || uniqueReviewed.some((key, index) => key !== migratableKeys[index])) {
+        return { ok: false, blockers: ['mcp_legacy_secret_review_mismatch'] };
+    }
+    return { ok: true, action, envNames: migratableKeys };
+}
+function withoutLegacySecretControls(patch) {
+    const sanitized = { ...patch };
+    delete sanitized[LEGACY_SECRET_ACTION];
+    delete sanitized[REVIEWED_LEGACY_ENV_KEYS];
+    return sanitized;
+}
+async function generateNextText(cli, before, action, name, input, legacyEnv, enabled, sensitiveInlineValues) {
+    if (action === 'enable' || action === 'disable') {
+        const text = setEnabledText(before, name, enabled === true);
+        return text === null
+            ? generatedFailure(['mcp_server_table_not_found'])
+            : { ok: true, text, cliUsed: false, fallbackUsed: true, warnings: ['guarded_targeted_patch_used'], blockers: [], publicError: null };
+    }
+    const operation = {
+        action,
+        name,
+        ...(input ? { server: input } : {})
+    };
+    const transformed = await cli.transform(before, operation).catch(() => ({
+        available: true, ok: false, used: true, text: null, unsupported_reason: null, public_error: 'codex_mcp_cli_transform_failed'
+    }));
+    const unsupportedReason = safeTransformUnsupportedReason(transformed.unsupported_reason, sensitiveInlineValues);
+    if (transformed.ok && typeof transformed.text === 'string') {
+        if (action === 'remove')
+            return { ok: true, text: transformed.text, cliUsed: true, fallbackUsed: false, warnings: [], blockers: [], publicError: null };
+        if (!input)
+            return generatedFailure(['mcp_mutation_input_missing']);
+        return {
+            ok: true,
+            text: replaceOrAppendMcpServer(transformed.text, name, renderMcpServerBlock(input, legacyEnv)),
+            cliUsed: true,
+            fallbackUsed: false,
+            warnings: [], blockers: [], publicError: null
+        };
+    }
+    if (transformed.used && !unsupportedReason) {
+        return generatedFailure(['codex_mcp_cli_mutation_failed'], 'codex_mcp_cli_mutation_failed');
+    }
+    if (action === 'remove') {
+        const text = removeServerText(before, name);
+        return text === null ? generatedFailure(['mcp_server_table_not_found']) : fallbackGenerated(text, unsupportedReason);
+    }
+    if (!input)
+        return generatedFailure(['mcp_mutation_input_missing']);
+    return fallbackGenerated(replaceOrAppendMcpServer(before, name, renderMcpServerBlock(input, legacyEnv)), unsupportedReason);
+}
+function mutationInputFromRaw(name, value) {
+    const url = typeof value.url === 'string' ? value.url : null;
+    const tools = isRecord(value.tools) ? value.tools : {};
+    const toolModes = {};
+    for (const [tool, raw] of Object.entries(tools)) {
+        if (isRecord(raw) && normalizeApprovalMode(raw.approval_mode))
+            toolModes[tool] = String(raw.approval_mode);
+    }
+    return {
+        name,
+        transport: url ? 'streamable-http' : 'stdio',
+        enabled: value.enabled !== false && value.disabled !== true,
+        ...(url ? { url } : {}),
+        ...(typeof value.command === 'string' ? { command: value.command } : {}),
+        ...(rawStringArray(value.args).length ? { args: rawStringArray(value.args) } : {}),
+        ...(rawStringArray(value.env_vars).length ? { env_vars: rawStringArray(value.env_vars) } : {}),
+        ...(typeof value.cwd === 'string' ? { cwd: value.cwd } : {}),
+        ...(value.experimental_environment === 'remote' ? { experimental_environment: 'remote' } : {}),
+        ...(typeof value.bearer_token_env_var === 'string' ? { bearer_token_env_var: value.bearer_token_env_var } : {}),
+        ...(typeof value.oauth_client_id === 'string' ? { oauth_client_id: value.oauth_client_id } : {}),
+        ...(typeof value.oauth_resource === 'string' ? { oauth_resource: value.oauth_resource } : {}),
+        ...(typeof value.startup_timeout_sec === 'number' ? { startup_timeout_sec: value.startup_timeout_sec } : {}),
+        ...(typeof value.tool_timeout_sec === 'number' ? { tool_timeout_sec: value.tool_timeout_sec } : {}),
+        ...(rawStringArray(value.enabled_tools).length ? { enabled_tools: rawStringArray(value.enabled_tools) } : {}),
+        ...(rawStringArray(value.disabled_tools).length ? { disabled_tools: rawStringArray(value.disabled_tools) } : {}),
+        ...(normalizeApprovalMode(value.default_tools_approval_mode ?? value.approval_mode) ? { default_tools_approval_mode: value.default_tools_approval_mode ?? value.approval_mode } : {}),
+        ...(Object.keys(toolModes).length ? { tool_approval_modes: toolModes } : {}),
+        ...(typeof value.required === 'boolean' ? { required: value.required } : {})
+    };
+}
+function inlineEnvironmentStringValues(servers) {
+    const values = [];
+    for (const server of Object.values(servers)) {
+        if (!isRecord(server.env))
+            continue;
+        for (const value of Object.values(server.env)) {
+            if (typeof value === 'string' && value.length > 0)
+                values.push(value);
+        }
+    }
+    return [...new Set(values)];
+}
+function mergeSensitiveValues(left, right) {
+    return [...new Set([...left, ...right].filter((value) => value.length > 0))];
+}
+function safeTransformUnsupportedReason(value, sensitiveInlineValues) {
+    if (value === null)
+        return null;
+    const redacted = redactMcpErrorWithSecrets(value, sensitiveInlineValues);
+    return SAFE_TRANSFORM_UNSUPPORTED_REASONS.has(redacted)
+        ? redacted
+        : 'codex_cli_mutation_unsupported';
+}
+function safeMutationPublicError(error, sensitiveInlineValues, fallback) {
+    const redacted = redactMcpErrorWithSecrets(error, sensitiveInlineValues);
+    return /^(?:mcp|codex)_[a-z0-9_]+$/.test(redacted) ? redacted : fallback;
+}
+function safeInventoryCli(cli) {
+    return {
+        async list(ref) {
+            try {
+                const result = await cli.list(ref);
+                if (result.ok)
+                    return { ...result, public_error: null };
+                return {
+                    available: result.available === true,
+                    ok: false,
+                    rows: [],
+                    public_error: result.available === false ? 'codex_cli_not_found' : 'codex_mcp_list_failed'
+                };
+            }
+            catch {
+                return { available: true, ok: false, rows: [], public_error: 'codex_mcp_list_failed' };
+            }
+        },
+        transform: (before, operation) => cli.transform(before, operation),
+        login: (ref, serverName, scopes) => cli.login(ref, serverName, scopes),
+        logout: (ref, serverName) => cli.logout(ref, serverName)
+    };
+}
+function inputFailure(action, name, scope, error) {
+    return failure(action, name, scope, error instanceof McpSecretPolicyError ? error.blockers : ['mcp_mutation_input_invalid'], redactMcpError(error));
+}
+function failure(action, name, scope, blockers, publicError = null, attempts = 0, cliUsed = false, fallbackUsed = false) {
+    return {
+        schema: MCP_MUTATION_SCHEMA, ok: false, action, name, scope, changed: false,
+        official_cli_used: cliUsed, fallback_used: fallbackUsed, backup_id: null, restart_required: false,
+        servers: [], blockers, warnings: [], attempts, public_error: publicError
+    };
+}
+function postWriteReceiptFailure(action, name, scope, changed, backupId, attempts, generated, error, sensitiveInlineValues) {
+    return {
+        schema: MCP_MUTATION_SCHEMA, ok: false, action, name, scope, changed,
+        official_cli_used: generated.cliUsed, fallback_used: generated.fallbackUsed,
+        backup_id: backupId, restart_required: changed, servers: [],
+        blockers: ['mcp_backup_receipt_failed_after_write'], warnings: generated.warnings,
+        attempts, public_error: safeMutationPublicError(error, sensitiveInlineValues, 'mcp_backup_receipt_failed_after_write')
+    };
+}
+function fallbackGenerated(text, reason) {
+    return { ok: true, text, cliUsed: false, fallbackUsed: true, warnings: [reason || 'codex_cli_unavailable_guarded_patch_used'], blockers: [], publicError: null };
+}
+function generatedFailure(blockers, publicError = null) {
+    return { ok: false, text: null, cliUsed: false, fallbackUsed: false, warnings: [], blockers, publicError };
+}
+function messageOf(error) { return error instanceof Error ? error.message : String(error); }

package/dist/core/mcp-config/oauth.js

@@ -0,0 +1,44 @@
+import { CodexMcpCliAdapter } from './codex-cli-adapter.js';
+import { rawServer, readMcpConfigDocument } from './config-reader.js';
+import { redactMcpError } from './redaction.js';
+import { normalizeMcpServerName } from './secret-policy.js';
+import { McpScopeError, resolveMcpScope } from './scope.js';
+export async function loginMcpServer(nameInput, scope, options = {}, scopes = []) {
+    return auth('login', nameInput, scope, options, scopes);
+}
+export async function logoutMcpServer(nameInput, scope, options = {}) {
+    return auth('logout', nameInput, scope, options, []);
+}
+async function auth(action, nameInput, scope, options, scopes) {
+    const name = normalizeMcpServerName(nameInput);
+    if (!name)
+        return failure(action, null, scope, ['invalid_mcp_server_name']);
+    try {
+        const ref = await resolveMcpScope(scope, options);
+        const document = await readMcpConfigDocument(ref);
+        const server = rawServer(document, name);
+        if (!server)
+            return failure(action, name, scope, ['mcp_server_not_found']);
+        if (typeof server.url !== 'string')
+            return failure(action, name, scope, ['mcp_oauth_requires_http_transport']);
+        const cli = options.cli ?? new CodexMcpCliAdapter({ ...(options.codexPath ? { codexPath: options.codexPath } : {}) });
+        const outcome = action === 'login' ? await cli.login(ref, name, scopes) : await cli.logout(ref, name);
+        if (!outcome.available)
+            return failure(action, name, scope, ['codex_cli_not_found'], outcome.public_error);
+        if (!outcome.ok)
+            return failure(action, name, scope, [`mcp_oauth_${action}_failed`], outcome.public_error);
+        return {
+            schema: 'sks.mcp-oauth.v1', ok: true, action, server: name, scope,
+            authenticated: action === 'login', blockers: [], public_error: null
+        };
+    }
+    catch (error) {
+        return failure(action, name, scope, [error instanceof McpScopeError ? error.code : `mcp_oauth_${action}_failed`], redactMcpError(error));
+    }
+}
+function failure(action, server, scope, blockers, publicError = null) {
+    return {
+        schema: 'sks.mcp-oauth.v1', ok: false, action, server, scope,
+        authenticated: null, blockers, public_error: publicError
+    };
+}

package/dist/core/mcp-config/redaction.js

@@ -0,0 +1,84 @@
+import os from 'node:os';
+import path from 'node:path';
+const SECRET_ASSIGNMENT = /\b(token|access[_-]?token|api[_-]?key|secret|client[_-]?secret|password|authorization|bearer|credential|private[_-]?key)\b(\s*[:=]\s*)([^\s,;]+)/gi;
+const BEARER = /\bBearer\s+[A-Za-z0-9._~+/=-]+/gi;
+const PROVIDER_SECRET = /(?:\bsk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{16,}\b|\bgh[pousr]_[A-Za-z0-9_]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bxox[baprs]-[A-Za-z0-9-]{16,}\b|\bAIza[A-Za-z0-9_-]{30,}\b)/i;
+const PROVIDER_SECRET_GLOBAL = /(?:\bsk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{16,}\b|\bgh[pousr]_[A-Za-z0-9_]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bxox[baprs]-[A-Za-z0-9-]{16,}\b|\bAIza[A-Za-z0-9_-]{30,}\b)/gi;
+const JWT_SECRET = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/i;
+const JWT_SECRET_GLOBAL = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/gi;
+export function isSensitiveMcpArgumentName(value) {
+    return /^--?(?:token|access[-_]?token|api[-_]?key|secret|client[-_]?secret|password|authorization|bearer|credential|private[-_]?key)(?:$|=)/i.test(String(value || ''));
+}
+export function looksLikeMcpSecretValue(value) {
+    const text = String(value || '').trim();
+    return PROVIDER_SECRET.test(text) || JWT_SECRET.test(text);
+}
+export function redactMcpUrl(value) {
+    try {
+        const url = new URL(value);
+        if (!['http:', 'https:'].includes(url.protocol) || url.origin === 'null')
+            return '[configured URL]';
+        return url.pathname && url.pathname !== '/' ? `${url.origin}/…` : url.origin;
+    }
+    catch {
+        return '[configured URL]';
+    }
+}
+export function redactMcpArgument(value) {
+    const text = String(value || '');
+    if (!text)
+        return text;
+    if (/^(?:https?):\/\//i.test(text))
+        return redactMcpUrl(text);
+    if (/^(?:[A-Za-z_][A-Za-z0-9_]*=).+/.test(text))
+        return `${text.slice(0, text.indexOf('=') + 1)}<redacted>`;
+    if (isSensitiveMcpArgumentName(text) || looksLikeMcpSecretValue(text))
+        return '<redacted>';
+    if (/(?:token|access[_-]?token|api[_-]?key|secret|client[_-]?secret|password|authorization|bearer|credential|private[_-]?key)/i.test(text))
+        return '<redacted>';
+    if (text.length > 512)
+        return `${text.slice(0, 128)}…`;
+    return text;
+}
+export function redactMcpError(value) {
+    const home = path.resolve(process.env.HOME || os.homedir());
+    return String(value instanceof Error ? value.message : value || '')
+        .replace(BEARER, 'Bearer <redacted>')
+        .replace(SECRET_ASSIGNMENT, (_match, key, separator) => `${key}${separator}<redacted>`)
+        .replace(PROVIDER_SECRET_GLOBAL, '<redacted>')
+        .replace(JWT_SECRET_GLOBAL, '<redacted>')
+        .replaceAll(home, '~')
+        .replace(/[\r\n\0]+/g, ' ')
+        .slice(0, 1024);
+}
+export function redactMcpErrorWithSecrets(value, sensitiveValues) {
+    let text = String(value instanceof Error ? value.message : value || '');
+    const secrets = [...new Set(sensitiveValues.filter((item) => typeof item === 'string' && item.length > 0))]
+        .sort((left, right) => right.length - left.length);
+    for (const secret of secrets)
+        text = text.split(secret).join('<redacted>');
+    return redactMcpError(text);
+}
+export function publicMcpCommand(value) {
+    const base = path.basename(String(value || '').trim());
+    return base && base.length <= 128 && /^[A-Za-z0-9._+-]+$/.test(base) ? base : '[configured command]';
+}
+export function sanitizeMcpArgs(values) {
+    const out = [];
+    let redactNext = false;
+    for (const raw of values.slice(0, 100)) {
+        const value = String(raw);
+        if (redactNext) {
+            out.push('<redacted>');
+            redactNext = false;
+            continue;
+        }
+        if (isSensitiveMcpArgumentName(value)) {
+            out.push(redactMcpArgument(value));
+            redactNext = !value.includes('=');
+            continue;
+        }
+        out.push(redactMcpArgument(value));
+    }
+    return out;
+}

package/dist/core/mcp-config/restore.js

@@ -0,0 +1,106 @@
+import { writeCodexConfigGuarded } from '../codex/codex-config-guard.js';
+import { withFileLock } from '../locks/file-lock.js';
+import { createMcpBackup, finalizeMcpBackup, loadMcpBackup } from './backup.js';
+import { CodexMcpCliAdapter } from './codex-cli-adapter.js';
+import { readMcpConfigDocument } from './config-reader.js';
+import { listMcpInventory } from './inventory.js';
+import { redactMcpError } from './redaction.js';
+import { McpScopeError, resolveMcpScope } from './scope.js';
+import { MCP_MUTATION_SCHEMA } from './types.js';
+export async function restoreMcpBackup(backupId, scope, options = {}) {
+    let ref;
+    try {
+        ref = await resolveMcpScope(scope, options);
+        if (scope === 'project' && options.confirmProjectMutation !== true)
+            throw new McpScopeError('mcp_project_mutation_confirmation_required');
+    }
+    catch (error) {
+        return failure(scope, [error instanceof McpScopeError ? error.code : 'mcp_scope_invalid'], redactMcpError(error));
+    }
+    try {
+        return await withFileLock({ lockPath: `${ref.configPath}.sks-mcp.lock`, timeoutMs: 10_000, staleMs: 60_000 }, async () => {
+            const [document, backup] = await Promise.all([readMcpConfigDocument(ref), loadMcpBackup(ref, backupId)]);
+            const rollback = await createMcpBackup(ref, document.text, 'restore', backup.metadata.server);
+            const write = await writeCodexConfigGuarded({
+                root: ref.root,
+                configPath: ref.configPath,
+                before: document.text,
+                cause: 'mcp-config-restore',
+                backupTag: 'mcp-config-restore',
+                ownershipVerified: true,
+                verifyUnchangedBeforeWrite: true,
+                expectedBeforeExists: document.exists,
+                preserveFastUiKeys: false,
+                preserveTextFormatting: true,
+                mutate: () => backup.text
+            });
+            if (!write.ok)
+                return failure(scope, [`mcp_config_write_${write.status}`]);
+            let finalized;
+            try {
+                finalized = await finalizeMcpBackup(rollback, backup.text);
+            }
+            catch (error) {
+                return {
+                    schema: MCP_MUTATION_SCHEMA,
+                    ok: false,
+                    action: 'restore',
+                    name: backup.metadata.server,
+                    scope,
+                    changed: write.changed,
+                    official_cli_used: false,
+                    fallback_used: true,
+                    backup_id: rollback.metadata.id,
+                    restart_required: write.changed,
+                    servers: [],
+                    blockers: ['mcp_backup_receipt_failed_after_write'],
+                    warnings: ['guarded_restore_used'],
+                    attempts: 1,
+                    public_error: redactMcpError(error)
+                };
+            }
+            const cli = options.cli ?? new CodexMcpCliAdapter({ ...(options.codexPath ? { codexPath: options.codexPath } : {}) });
+            const inventory = await listMcpInventory(scope, { ...options, cli });
+            return {
+                schema: MCP_MUTATION_SCHEMA,
+                ok: true,
+                action: 'restore',
+                name: backup.metadata.server,
+                scope,
+                changed: write.changed,
+                official_cli_used: false,
+                fallback_used: true,
+                backup_id: finalized.id,
+                restart_required: write.changed,
+                servers: inventory.servers,
+                blockers: [],
+                warnings: ['changes_apply_to_new_codex_sessions', 'guarded_restore_used'],
+                attempts: 1,
+                public_error: null
+            };
+        });
+    }
+    catch (error) {
+        return failure(scope, [messageOf(error).startsWith('file_lock_timeout:') ? 'mcp_config_busy' : 'mcp_restore_failed'], redactMcpError(error));
+    }
+}
+function failure(scope, blockers, publicError = null) {
+    return {
+        schema: MCP_MUTATION_SCHEMA,
+        ok: false,
+        action: 'restore',
+        name: null,
+        scope,
+        changed: false,
+        official_cli_used: false,
+        fallback_used: false,
+        backup_id: null,
+        restart_required: false,
+        servers: [],
+        blockers,
+        warnings: [],
+        attempts: 0,
+        public_error: publicError
+    };
+}
+function messageOf(error) { return error instanceof Error ? error.message : String(error); }

package/dist/core/mcp-config/scope.js

@@ -0,0 +1,69 @@
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+export class McpScopeError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'McpScopeError';
+    }
+}
+export async function resolveMcpScope(scope, options = {}) {
+    if (scope === 'global') {
+        const requestedHome = path.resolve(options.home || process.env.HOME || os.homedir());
+        const home = await fsp.realpath(requestedHome).catch(() => requestedHome);
+        const codexHome = path.join(home, '.codex');
+        await assertSafeDirectory(codexHome, home, false);
+        const configPath = path.join(codexHome, 'config.toml');
+        await assertSafeConfig(configPath, home);
+        return { scope, configPath, codexHome, root: home };
+    }
+    if (options.projectTrusted !== true)
+        throw new McpScopeError('mcp_project_not_trusted');
+    if (!options.projectRoot)
+        throw new McpScopeError('mcp_project_root_required');
+    const requestedRoot = path.resolve(options.projectRoot);
+    const root = await fsp.realpath(requestedRoot).catch(() => {
+        throw new McpScopeError('mcp_project_root_unreadable');
+    });
+    const rootStat = await fsp.lstat(root).catch(() => null);
+    if (!rootStat?.isDirectory() || rootStat.isSymbolicLink())
+        throw new McpScopeError('mcp_project_root_invalid');
+    const codexHome = path.join(root, '.codex');
+    await assertSafeDirectory(codexHome, root, true);
+    const configPath = path.join(codexHome, 'config.toml');
+    await assertSafeConfig(configPath, root);
+    return { scope, configPath, codexHome, root };
+}
+export function isPathInside(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+async function assertSafeDirectory(directory, boundary, strictNoSymlink) {
+    const stat = await fsp.lstat(directory).catch((error) => errorCode(error) === 'ENOENT' ? null : Promise.reject(error));
+    if (!stat)
+        return;
+    if (strictNoSymlink && stat.isSymbolicLink())
+        throw new McpScopeError('mcp_project_codex_home_symlink_refused');
+    if (!stat.isDirectory() && !stat.isSymbolicLink())
+        throw new McpScopeError('mcp_codex_home_not_directory');
+    const resolved = await fsp.realpath(directory).catch(() => null);
+    if (!resolved || !isPathInside(boundary, resolved))
+        throw new McpScopeError('mcp_codex_home_escape_refused');
+}
+async function assertSafeConfig(configPath, boundary) {
+    const stat = await fsp.lstat(configPath).catch((error) => errorCode(error) === 'ENOENT' ? null : Promise.reject(error));
+    if (!stat)
+        return;
+    if (stat.isSymbolicLink())
+        throw new McpScopeError('mcp_config_symlink_refused');
+    if (!stat.isFile())
+        throw new McpScopeError('mcp_config_not_regular_file');
+    const resolved = await fsp.realpath(configPath).catch(() => null);
+    if (!resolved || !isPathInside(boundary, resolved))
+        throw new McpScopeError('mcp_config_escape_refused');
+}
+function errorCode(error) {
+    return error && typeof error === 'object' && 'code' in error ? String(error.code) : '';
+}