openrod 0.0.0 → 0.1.0

package/server/setup-egress.js

@@ -0,0 +1,133 @@
+import { DEFAULT_ADVANCED, listPolicies, removePolicy, validatePolicy, writePolicy } from './egress.js'
+import { blockOverlap, covers, protectCoverage, readOrg, serializeOrgWrite, syncAllWhileLocked } from './org.js'
+import { readSetupMembers } from './setup-members.js'
+import { usableSetup, SETUP_ID } from './setups.js'
+import { hostMatches } from '../src/lib/egress.js'
+import { inSetupPolicy } from '../src/lib/setup-network.js'
+
+// ---- one egress policy per MCPs & Skills setup -------------------------------
+//
+// A saved setup whose MCPs reach the network gets one allow policy,
+// policies/egress/setup-<id>.json, that applies to the sandboxes using the
+// setup (server/setup-members.js). It lists the hosts the setup's MCPs reach
+// at runtime and their own sign-in hosts, never build hosts such as the npm
+// registry: the isolated builder reaches those, not sandboxes. Hosts an MCP
+// sends credentials to, and sign-in services an MCP's metadata names, stay out
+// too: each sandbox approves those when it enables the setup. Hosts the
+// organization blocks stay out. People may add hosts and ports in Egress; a
+// recompute keeps them.
+
+const fail = (message, status = 400) => Object.assign(new Error(message), { status })
+const HOST = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/
+const PHASES = ['runtime', 'auth']
+const NONE = { applied: [], failed: [] }
+const uniq = (items) => [...new Set(items)]
+
+export const setupPolicyId = (setupId) => {
+  if (!SETUP_ID.test(String(setupId ?? ''))) throw fail('Unknown MCPs & Skills setup.')
+  return `setup-${setupId}`
+}
+
+// Host and port → the MCPs that need them, in the order the setup lists them.
+function hostsOf(setup, keep) {
+  const out = new Map()
+  for (const item of usableSetup(setup).items) for (const r of item.requirements ?? []) {
+    const host = String(r.host ?? '').trim().toLowerCase().replace(/\.$/, ''), port = Number(r.port ?? 443)
+    if (!PHASES.includes(r.phase) || !keep(item, r) || !HOST.test(host) || !Number.isInteger(port) || port < 1 || port > 65535) continue
+    const entry = out.get(`${host}:${port}`) ?? { host, port, items: [] }
+    if (!entry.items.includes(item.name)) entry.items.push(item.name)
+    out.set(`${host}:${port}`, entry)
+  }
+  return [...out.values()]
+}
+export const setupHosts = (setup) => hostsOf(setup, inSetupPolicy)
+// The hosts each sandbox approves when it enables the setup instead.
+export const approvalHosts = (setup) => hostsOf(setup, (item, r) => !inSetupPolicy(item, r))
+const byHost = (needs) => [...needs.reduce((all, { host, items }) => all.set(host, { host, items: uniq([...(all.get(host)?.items ?? []), ...items]) }), new Map()).values()]
+// Only an allow policy carrying this setup's marker is the setup's to rewrite or delete.
+const owned = (policy, setupId) => policy?.action === 'allow' && policy.setup?.id === setupId
+
+// The setup's own allow policy when it lets a sandbox using the setup (or the
+// setup a Quick-setup snapshot was prepared from) reach the requirement.
+export const setupPolicyFor = (policies, setup, requirement) => {
+  const ids = [setup.id, setup.preparedFrom?.id].filter(Boolean)
+  return policies.find((p) => p.action === 'allow' && (p.appliesTo.setups ?? []).some((id) => ids.includes(id))
+    && p.destinations.some((d) => hostMatches(d, requirement.host)) && p.advanced.ports.includes(Number(requirement.port ?? 443))) ?? null
+}
+
+// `dir`, `org`, `sync` and `members` are for tests.
+export function createSetupEgress({ dir, org = readOrg, sync = syncAllWhileLocked, members = readSetupMembers } = {}) {
+  // Automatic and manual changes share coverage checks and the same queue.
+  const serial = serializeOrgWrite
+  // Only the sandboxes either version reaches. Without any, the gateway is
+  // not contacted; when it is unreachable, the sweeper applies it later.
+  async function apply(versions) {
+    try {
+      const stored = Object.values(await members())
+      const reach = versions.some((p) => p && (p.appliesTo.everyone || p.appliesTo.groups.length || p.appliesTo.sandboxes.length || stored.some((ids) => p.appliesTo.setups.some((id) => ids.includes(id)))))
+      return reach ? await sync({ only: covers(versions) }) : NONE
+    } catch (error) { return { error: error.rawMessage ?? error.message } }
+  }
+  const syncSetupPolicy = (setup) => serial(async () => {
+    if (!SETUP_ID.test(String(setup?.id ?? '')) || !Array.isArray(setup.items) || typeof setup.name !== 'string') throw fail('Unknown MCPs & Skills setup.')
+    // A Quick-setup snapshot uses the policy of the setup it was prepared from.
+    if (setup.preparedFrom) return null
+    const id = setupPolicyId(setup.id)
+    const [organization, policies] = await Promise.all([org(), listPolicies(dir)])
+    const existing = policies.find((p) => p.id === id) ?? null
+    // A rule switched to Block in Egress, or someone else's rule with this id, is left alone.
+    if (existing && !owned(existing, setup.id)) throw fail(`The rule “${existing.name}” isn’t an allow rule kept by this setup, so it was left unchanged. Edit it in Network › Egress.`, 409)
+    const advanced = existing?.advanced ?? { ...DEFAULT_ADVANCED, ports: [] }
+    // OpenShell can't combine an audit or private-address allow with any block
+    // on the same host, so such a policy keeps clear of every block.
+    const strict = advanced.enforcement === 'audit' || advanced.privateIps.length > 0
+    const blocks = [...organization.blocked, ...policies.filter((p) => p.action === 'block' && (strict || p.appliesTo.everyone)).flatMap((p) => p.destinations)]
+    const hosts = new Map(), blocked = [], ports = []
+    for (const need of setupHosts(setup)) {
+      if (blockOverlap(blocks, need.host)) { if (!blocked.includes(need.host)) blocked.push(need.host); continue }
+      ports.push(need.port)
+      const entry = hosts.get(need.host) ?? { host: need.host, items: [] }
+      entry.items = uniq([...entry.items, ...need.items])
+      hosts.set(need.host, entry)
+    }
+    const required = [...hosts.keys()]
+    const extras = (existing?.destinations ?? []).filter((d) => !(existing.setup?.required ?? []).includes(d) && !required.includes(d))
+    const destinations = [...required, ...extras]
+    if (!destinations.length) {
+      if (existing) {
+        await protectCoverage(policies, policies.filter((p) => p.id !== id))
+        await removePolicy(id, dir); await apply([existing])
+      }
+      return null
+    }
+    // Ports people added stay; ports only a removed MCP needed close.
+    const opened = uniq([...advanced.ports.filter((p) => !(existing?.setup?.ports ?? []).includes(p)), ...ports])
+    const policy = validatePolicy({
+      id,
+      name: existing?.name ?? `MCPs & Skills: ${setup.name}`.slice(0, 80),
+      action: 'allow',
+      destinations,
+      appliesTo: existing ? { ...existing.appliesTo, setups: uniq([...existing.appliesTo.setups, setup.id]) } : { everyone: false, groups: [], sandboxes: [], setups: [setup.id] },
+      advanced: { ...advanced, ports: opened.length ? opened : DEFAULT_ADVANCED.ports },
+      setup: { id: setup.id, name: setup.name.replace(/[\x00-\x1f\x7f]/g, ''), required, ports: uniq(ports) },
+    })
+    const changed = JSON.stringify(policy) !== JSON.stringify(existing)
+    if (changed) {
+      await protectCoverage(policies, [...policies.filter((p) => p.id !== id), policy])
+      await writePolicy(policy, dir)
+    }
+    return { id, name: policy.name, created: !existing, destinations: policy.destinations, hosts: [...hosts.values()], blocked, approval: byHost(approvalHosts(setup)), sync: changed ? await apply([existing, policy]) : NONE }
+  })
+  const removeSetupPolicy = (setupId) => serial(async () => {
+    const id = setupPolicyId(setupId)
+    const policies = await listPolicies(dir)
+    const existing = policies.find((p) => p.id === id)
+    if (!owned(existing, setupId)) return { removed: false, sync: NONE }
+    await protectCoverage(policies, policies.filter((p) => p.id !== id))
+    await removePolicy(id, dir)
+    return { removed: true, sync: await apply([existing]) }
+  })
+  return { syncSetupPolicy, removeSetupPolicy }
+}
+
+export const { syncSetupPolicy, removeSetupPolicy } = createSetupEgress()

package/server/setup-http.js

@@ -0,0 +1,47 @@
+import https from 'node:https'
+import { lookup } from 'node:dns/promises'
+import { isIP } from 'node:net'
+import { publicAddress } from './activity-delivery.js'
+import { fail } from './setup-discovery.js'
+import { readOrg, blockedBy } from './org.js'
+import { listPolicies, blockedByPolicy } from './egress.js'
+import { hostMatches } from '../src/lib/egress.js'
+
+// Read-only OAuth metadata discovery runs in the trusted control plane. Pin every
+// socket to checked public DNS answers; never follow redirects or proxy env vars.
+export function publicHTTPS(value) {
+  const url = new URL(value)
+  if (url.protocol !== 'https:' || url.username || url.password || url.hash || url.port && url.port !== '443' || url.hostname.endsWith('.local') || url.hostname.endsWith('.localhost')) throw fail('Sign-in requires a public HTTPS service on port 443.')
+  return url
+}
+export async function oauthFetch(input, init = {}, approvedHosts = new Set(), pendingHosts = new Set()) {
+  const url = publicHTTPS(typeof input === 'string' || input instanceof URL ? input : input.url)
+  if (!approvedHosts.has(url.hostname)) { pendingHosts.add(url.hostname); throw fail('Review the additional sign-in destination.', 409) }
+  const [org, policies] = await Promise.all([readOrg(), listPolicies()])
+  if (blockedBy(org, [url.hostname]) || blockedByPolicy(policies, { name: '', group: null }, [url.hostname], hostMatches)) throw fail('Sign-in destination is blocked by organization policy.', 403)
+  const host = url.hostname.replace(/^\[|\]$/g, '')
+  const addresses = isIP(host) ? [{ address: host, family: isIP(host) }] : await lookup(host, { all: true })
+  if (!addresses.length || addresses.some(a => !publicAddress(a.address))) throw fail('Sign-in destination resolves to a private or reserved address.')
+  const chosen = addresses[0]
+  const method = init.method || input.method || 'GET'
+  if (method !== 'GET') throw fail('Sign-in discovery only permits metadata reads.')
+  const headers = Object.fromEntries(new Headers(init.headers || input.headers))
+  delete headers.host
+  const body = init.body === undefined ? (input instanceof Request && !['GET', 'HEAD'].includes(method) ? await input.text() : undefined) : String(init.body)
+  if (body && Buffer.byteLength(body) > 128 * 1024) throw fail('Sign-in request is too large.')
+  return new Promise((resolve, reject) => {
+    const request = https.request(url, { method, headers, agent: false, signal: AbortSignal.timeout(15000), lookup: (_, options, cb) => options.all ? cb(null, [chosen]) : cb(null, chosen.address, chosen.family) }, response => {
+      const chunks = []; let size = 0
+      response.on('data', chunk => { size += chunk.length; if (size > 1024 * 1024) request.destroy(); else chunks.push(chunk) })
+      response.on('end', () => {
+        const status = response.statusCode
+        const value = new Response([204, 205, 304].includes(status) ? null : Buffer.concat(chunks), { status, headers: response.headers })
+        Object.defineProperty(value, 'url', { value: url.href })
+        resolve(value)
+      })
+      response.on('error', () => reject(fail('Sign-in HTTPS response failed.')))
+    })
+    request.on('error', () => reject(fail('Sign-in HTTPS request failed. Check access and retry.')))
+    request.end(body)
+  })
+}

package/server/setup-installer.py

@@ -0,0 +1,289 @@
+"""Trusted offline installer. Imported commands and skill scripts are never run."""
+import base64, hashlib, json, os, pathlib, re, shutil, sys, tempfile
+import fcntl
+import tomllib
+
+HOME = pathlib.Path(os.environ.get('OPENSHELL_SETUP_HOME', '/sandbox'))
+if 'parse_agent_json' not in globals(): exec((pathlib.Path(__file__).parent / 'setup-json.py').read_text())
+CATALOG = json.loads(globals().get('SETUP_TARGET_CATALOG') or (pathlib.Path(__file__).parent.parent / 'shared/setup-targets.json').read_text())
+TARGETS = {t['id']: t for t in CATALOG if t.get('config') and t.get('skills')}
+
+def find_executable(command):
+    found = shutil.which(command)
+    if found or '/' in command: return found
+    # Non-login checks must find image-installed tools without sourcing profiles.
+    roots = [pathlib.Path(p) for p in ('/usr/local/bin', '/usr/bin', '/opt/bin')]
+    roots += [HOME / p for p in ('.local/bin', '.npm-global/bin', '.bun/bin', '.opencode/bin', 'bin', '.cargo/bin')]
+    roots += sorted((HOME / '.nvm/versions/node').glob('*/bin')) + [pathlib.Path('/opt/node/bin')]
+    for root in roots:
+        candidate = root / command
+        if candidate.is_file() and os.access(candidate, os.X_OK): return str(candidate)
+    return None
+
+def network_executable(filename):
+    if not filename: return None
+    resolved = os.path.realpath(filename)
+    if pathlib.Path(resolved).name == 'kiro-cli':
+        chat = pathlib.Path(resolved).with_name('kiro-cli-chat')
+        if chat.is_file(): return network_executable(str(chat))
+    # Copilot's npm loader spawns the platform package, not the Node interpreter.
+    if pathlib.Path(resolved).name == 'npm-loader.js' and pathlib.Path(resolved).parent.name == 'copilot':
+        package = pathlib.Path(resolved).parent
+        arch = 'arm64' if os.uname().machine in ('aarch64', 'arm64') else 'x64'
+        try: glibc = bool(os.confstr('CS_GNU_LIBC_VERSION'))
+        except (ValueError, OSError): glibc = False
+        for platform in (['linux'] if glibc else ['linuxmusl', 'linux']):
+            name = 'copilot-' + platform + '-' + arch
+            for candidate in (package / 'node_modules/@github' / name / 'copilot', package.parent / name / 'copilot'):
+                if candidate.is_file(): return network_executable(str(candidate))
+        return None
+    try:
+        with open(resolved, 'rb') as handle:
+            if handle.read(4) == b'\x7fELF': return resolved
+    except OSError: pass
+    # Codex's npm shim launches a native binary, which owns its network calls.
+    if pathlib.Path(resolved).name == 'codex.js':
+        package = pathlib.Path(resolved).parent.parent
+        arch = 'arm64' if os.uname().machine in ('aarch64', 'arm64') else 'x64'
+        triple = 'aarch64-unknown-linux-musl' if arch == 'arm64' else 'x86_64-unknown-linux-musl'
+        roots = [package / 'vendor', package / 'node_modules/@openai' / ('codex-linux-' + arch) / 'vendor', package.parent / ('codex-linux-' + arch) / 'vendor']
+        for base in roots:
+            for suffix in ('bin/codex', 'codex/codex'):
+                candidate = base / triple / suffix
+                if candidate.is_file():
+                    found = network_executable(str(candidate))
+                    if found: return found
+        return None
+    # Known Node shebangs run the Node interpreter; other spawned programs still need separate grants.
+    try:
+        with open(resolved, 'rb') as handle: first = handle.readline(160).strip()
+        if first in (b'#!/usr/bin/env node', b'#!/usr/bin/node', b'#!/usr/local/bin/node'):
+            return network_executable(shutil.which('node'))
+    except OSError: pass
+    # Other script interpreters require a supported adapter.
+    return None
+
+def toml_value(value):
+    if isinstance(value, dict): return '{ ' + ', '.join(json.dumps(k) + ' = ' + toml_value(v) for k, v in value.items()) + ' }'
+    if isinstance(value, list): return '[' + ', '.join(toml_value(v) for v in value) + ']'
+    return json.dumps(value)
+
+def digest(raw): return hashlib.sha256(raw).hexdigest()
+def safe_path(relative):
+    parts = pathlib.PurePosixPath(relative).parts
+    if not parts or relative.startswith('/') or any(p in ('..', '.') for p in parts): raise ValueError('Unsafe destination')
+    current = HOME
+    if current.is_symlink(): raise ValueError('Sandbox home is a symlink')
+    for p in parts:
+        current = current / p
+        if current.is_symlink(): raise ValueError('Destination contains a symlink')
+    return current
+
+def read(relative):
+    p = safe_path(relative)
+    if not p.exists(): return None
+    if not p.is_file() or p.stat().st_size > 8 * 1024 * 1024: raise ValueError('Destination is not a supported regular file')
+    with open(p, 'rb') as f: return f.read()
+
+def write(relative, data, mode=0o600):
+    p = safe_path(relative); p.parent.mkdir(parents=True, exist_ok=True)
+    safe_path(relative)
+    if data is None:
+        if p.exists(): p.unlink()
+        return
+    fd, temp = tempfile.mkstemp(prefix='.openshell-', dir=p.parent)
+    try:
+        with os.fdopen(fd, 'wb') as f:
+            f.write(data); os.fchmod(f.fileno(), mode)
+        os.replace(temp, p)
+    finally:
+        if os.path.exists(temp): os.unlink(temp)
+
+def connected_config(item):
+    config = item.get('config')
+    if not config or not item.get('credentialRef'): return config
+    aliases = set(item['credentialRef']['aliases'].values())
+    def resolve(value):
+        if not isinstance(value, str): return value
+        def replace(match):
+            key = match.group(1)
+            bound = os.environ.get(key, '')
+            if key not in aliases or not bound.startswith('openshell:resolve:env:'): raise ValueError('Gateway credential handles are not available yet. Check requirements and retry.')
+            return bound
+        return re.sub(r'openshell:resolve:env:([A-Za-z0-9_]+)', replace, value)
+    return {key: {k: resolve(v) for k, v in value.items()} if key in ('env', 'headers') else value for key, value in config.items()}
+
+def remove_managed_toml(text, block):
+    if text.count(block) == 1: return text.replace(block, '', 1)
+    # Codex may reformat the file or append its own tables inside our markers.
+    # Check values first, remove only owned tables, then verify everything else.
+    original = tomllib.loads(text)
+    owned = tomllib.loads(block).get('mcp_servers', {})
+    if not owned or any(original.get('mcp_servers', {}).get(k) != v for k, v in owned.items()):
+        raise ValueError('Managed MCP configuration changed; resolve it before updating or removing')
+    kept = []; skipping = False
+    for line in text.splitlines(keepends=True):
+        if re.match(r'^\s*\[.*\]\s*(?:#.*)?$', line):
+            try: section = tomllib.loads(line)
+            except tomllib.TOMLDecodeError: raise ValueError('Managed MCP configuration could not be safely updated')
+            servers = section.get('mcp_servers', {})
+            skipping = bool(servers) and set(servers).issubset(owned)
+        if not skipping or line.lstrip().startswith('#'): kept.append(line)
+    result = ''.join(kept)
+    for line in block.splitlines(keepends=True):
+        if line.startswith('# openshell-setup:'): result = result.replace(line, '')
+    expected = json.loads(json.dumps(original))
+    for key in owned: del expected['mcp_servers'][key]
+    actual = tomllib.loads(result)
+    if not expected.get('mcp_servers'): expected.pop('mcp_servers', None)
+    if not actual.get('mcp_servers'): actual.pop('mcp_servers', None)
+    if actual != expected: raise ValueError('Managed MCP configuration could not be safely updated')
+    return result
+
+def mcp_names(items, occupied, sid, prior=None):
+    names = {}; occupied = set(occupied)
+    for item in items:
+        name = (prior or {}).get(item['id'])
+        if name:
+            if name in occupied: raise ValueError('Managed MCP name collision')
+        else:
+            name = re.sub(r'[^a-zA-Z0-9_-]+', '-', item.get('name') or 'mcp').strip('-')[:60] or 'mcp'
+            if name in occupied: name += '-' + sid[:8] + '-' + item['id'][:8]
+            if name in occupied: raise ValueError('MCP name collision')
+        names[item['id']] = name; occupied.add(name)
+    return names
+
+def target_mcp_config(kind, config):
+    value = dict(config)
+    if kind in ('claude', 'droid'): value['type'] = 'http' if 'url' in value else 'stdio'
+    elif kind == 'copilot':
+        value['type'] = 'http' if 'url' in value else 'local'
+        value['tools'] = ['*']
+    elif kind == 'antigravity' and 'url' in value: value['serverUrl'] = value.pop('url')
+    elif kind == 'opencode':
+        if 'url' in value:
+            if value.get('env'): raise ValueError('OpenCode remote MCPs do not support environment settings; use headers instead')
+            value['type'] = 'remote'
+        else:
+            value['type'] = 'local'
+            value['command'] = [value['command']] + value.pop('args', [])
+            if 'env' in value: value['environment'] = value.pop('env')
+        value['enabled'] = True
+    return value
+
+def run(request):
+    operation = request['operation']; setup = request['setup']; targets = request['targets']
+    sid = setup['id']
+    if not re.fullmatch(r'[a-f0-9]{24}', sid) or not targets or any(t not in TARGETS for t in targets): raise ValueError('Invalid setup or target')
+    manifest_path = '.openshell/installed-setups/' + sid + '.json'
+    original_manifest = read(manifest_path)
+    previous = json.loads(original_manifest) if original_manifest else None
+    required = {TARGETS[t]['command']: find_executable(TARGETS[t]['command']) for t in targets}
+    if any(i['kind'] == 'mcp' for i in setup['items']): required['node'] = shutil.which('node')
+    for item in setup['items']:
+        if item['kind'] == 'mcp' and (item.get('config') or {}).get('command'):
+            required[item['config']['command']] = shutil.which(item['config']['command'])
+    if operation == 'probe': return {'executables': required, 'networkExecutables': {k: network_executable(v) for k, v in required.items()}, 'installed': previous is not None, 'revision': previous and previous['revision'], 'items': (previous or {}).get('items', []), 'targets': previous and previous['targets'], 'mcpNames': {c['target']: c.get('names', {}) for c in (previous or {}).get('configs', [])}}
+    if previous and sorted(previous['targets']) != sorted(targets): raise ValueError('Select the originally assigned agents before reapplying or removing this Setup')
+    if operation not in ('apply', 'remove'): raise ValueError('Unknown operation')
+    if operation == 'apply' and any(not p for p in required.values()): raise ValueError('Required agent or MCP executable is missing from the image')
+    if operation == 'apply':
+        setup = dict(setup, items=[dict(item, config=connected_config(item)) if item['kind'] == 'mcp' else item for item in setup['items']])
+    plans = {}; modes = {}; owned_files = {}; owned_configs = []; skill_names = {}
+    if operation == 'remove' and not previous: return {'status': 'not-installed'}
+    for target in targets:
+        adapter = TARGETS[target]
+        config_path, skill_path = adapter['config'], adapter['skills']
+        if adapter.get('alternateConfig') and safe_path(adapter['alternateConfig']).exists(): config_path = adapter['alternateConfig']
+        mcps = [i for i in setup['items'] if i['kind'] == 'mcp']
+        if mcps or any(c['target'] == target for c in (previous or {}).get('configs', [])):
+            raw = read(config_path); text = (raw or b'').decode('utf-8')
+            if target == 'codex':
+                # Parse first; never append to a broken config. Managed TOML is
+                # a separately delimited tail so unrelated formatting survives.
+                tomllib.loads(text)
+                begin = '# openshell-setup:' + sid + ':begin\n'; end = '# openshell-setup:' + sid + ':end\n'
+                prior = next((c for c in (previous or {}).get('configs', []) if c['target'] == target), None)
+                if prior:
+                    text = remove_managed_toml(text, prior['block'])
+                names = mcp_names(mcps, tomllib.loads(text).get('mcp_servers', {}), sid, (prior or {}).get('names'))
+                block = begin
+                for item in mcps:
+                    block += '[mcp_servers.' + json.dumps(names[item['id']]) + ']\n'
+                    for field, value in item['config'].items(): block += ('http_headers' if field == 'headers' else field) + ' = ' + toml_value(value) + '\n'
+                block += end
+                if operation == 'apply': text = text + ('\n' if text and not text.endswith('\n') else '') + block
+                tomllib.loads(text)
+                plans[config_path] = text.encode(); owned_configs.append({'target': target, 'block': block, 'names': names})
+            else:
+                doc = parse_agent_json(text or '{}') if adapter['format'] == 'opencode' else json.loads(text or '{}')
+                key_name = adapter['key']
+                if not isinstance(doc, dict) or not isinstance(doc.get(key_name, {}), dict): raise ValueError('Invalid MCP configuration')
+                servers = doc.setdefault(key_name, {})
+                prior = next((c for c in (previous or {}).get('configs', []) if c['target'] == target), None)
+                if prior:
+                    for key, value in prior['values'].items():
+                        if servers.get(key) != value: raise ValueError('Managed MCP configuration changed or name is already used')
+                        del servers[key]
+                names = mcp_names(mcps, servers, sid, (prior or {}).get('names'))
+                values = {}
+                if operation == 'apply':
+                    for item in mcps:
+                        key = names[item['id']]
+                        value = target_mcp_config(adapter['format'], item['config'])
+                        servers[key] = value; values[key] = value
+                plans[config_path] = (json.dumps(doc, indent=2) + '\n').encode(); owned_configs.append({'target': target, 'values': values, 'names': names})
+        if operation == 'apply':
+            skills = [i for i in setup['items'] if i['kind'] == 'skill']
+            root = safe_path(skill_path)
+            prior_names = (previous or {}).get('skillNames', {}).get(target, {})
+            occupied = {p.name for p in root.iterdir()} if root.exists() else set()
+            names = mcp_names(skills, occupied - set(prior_names.values()), sid, prior_names)
+            skill_names[target] = names
+            for item in skills:
+                for f in item['files']:
+                    relative = skill_path + '/' + names[item['id']] + '/' + f['path']
+                    if f.get('encoding') not in (None, 'utf8', 'base64'): raise ValueError('Unsupported skill file encoding')
+                    content = base64.b64decode(f['content'], validate=True) if f.get('encoding') == 'base64' else f['content'].encode()
+                    existing = read(relative)
+                    if existing is not None and ((previous or {}).get('files', {}).get(relative) != digest(existing)): raise ValueError('Skill file already exists or was modified')
+                    plans[relative] = content; modes[relative] = 0o700 if f.get('executable') else 0o600; owned_files[relative] = digest(content)
+    # Retire legacy generated paths only after checking every owned file for edits.
+    # These deletions join the same rollback plan as the new readable paths.
+    if operation == 'apply' and previous:
+        for relative, expected in previous['files'].items():
+            if relative in owned_files: continue
+            raw = read(relative)
+            if raw is not None and digest(raw) != expected: raise ValueError('Managed skill was modified; resolve it before migrating')
+            plans[relative] = None
+    if operation == 'remove':
+        for relative, expected in previous['files'].items():
+            raw = read(relative)
+            if raw is not None and digest(raw) != expected: raise ValueError('Managed skill was modified; remove the assignment manually to preserve changes')
+            plans[relative] = None
+        plans[manifest_path] = None
+    else:
+        plans[manifest_path] = json.dumps({'items': [i['id'] for i in setup['items']], 'revision': setup['revision'], 'targets': targets, 'files': owned_files, 'configs': owned_configs, 'skillNames': skill_names}).encode()
+    originals = {p: read(p) for p in plans}; original_modes = {p: safe_path(p).stat().st_mode & 0o777 for p in plans if safe_path(p).exists()}; completed = []
+    try:
+        for p, data in plans.items(): write(p, data, modes.get(p, original_modes.get(p, 0o600))); completed.append(p)
+        for p, data in plans.items():
+            if read(p) != data: raise ValueError('Written files could not be verified')
+    except Exception:
+        for p in reversed(completed): write(p, originals[p], original_modes.get(p, 0o600))
+        raise
+    return {'status': 'installed' if operation == 'apply' else 'removed', 'filesVerified': len(plans), 'restartRequired': True, 'connectivityVerified': False}
+
+try:
+    request = json.load(sys.stdin)
+    if request['operation'] == 'probe':
+        print(json.dumps(run(request))); sys.exit(0)
+    lock = safe_path('.openshell/setup.lock'); lock.parent.mkdir(parents=True, exist_ok=True)
+    with os.fdopen(os.open(lock, os.O_WRONLY | os.O_CREAT | os.O_NOFOLLOW, 0o600), 'a') as handle:
+        fcntl.flock(handle, fcntl.LOCK_EX)
+        print(json.dumps(run(request)))
+except Exception as error:
+    # Never echo malformed config content, paths, credentials or child output.
+    known = isinstance(error, ValueError) and not isinstance(error, (json.JSONDecodeError, tomllib.TOMLDecodeError))
+    print(json.dumps({'error': str(error) if known else 'Setup operation failed; check filesystem access and existing configuration.'}))
+    sys.exit(1)

package/server/setup-json.py

@@ -0,0 +1,8 @@
+"""Parse agent JSONC without interpreting expressions or changing string values."""
+import json, re
+
+def parse_agent_json(text):
+    string = r'"(?:\\.|[^"\\])*"'
+    clean = re.sub(string + r'|//[^\n]*|/\*[\s\S]*?\*/', lambda m: m[0] if m[0].startswith('"') else ' ', text)
+    clean = re.sub(string + r'|,\s*[}\]]', lambda m: m[0] if m[0].startswith('"') else m[0][1:], clean)
+    return json.loads(clean)

package/server/setup-members.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { scopedStateDirectory } from './paths.js'
+
+// Gateway endpoint + immutable sandbox id → the MCPs & Skills setups it uses.
+// Names can be reused, including on another gateway, and cannot identify grants.
+// A Quick-setup snapshot also records the setup it was prepared from.
+const membersFile = () => path.join(scopedStateDirectory(), 'setup-members.json')
+const NAME = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/
+const ID = /^[a-f0-9]{24}$/
+const fail = (message, status = 400) => Object.assign(new Error(message), { status })
+const ids = (input) => [...new Set((Array.isArray(input) ? input : []).map(String).filter((id) => ID.test(id)))]
+const identityPart = (value, limit) => typeof value === 'string' && value.length > 0 && value.length <= limit && value.trim() === value && !/[\x00-\x1f\x7f]/.test(value)
+const keyFor = (gateway, id) => identityPart(gateway, 2048) && identityPart(id, 256) ? JSON.stringify([gateway, id]) : null
+const storedKey = (key) => {
+  try { const parts = JSON.parse(key); return Array.isArray(parts) && parts.length === 2 && keyFor(...parts) === key } catch { return false }
+}
+
+// Missing ids and pre-identity name-only records are deliberately ignored.
+// Re-enabling a setup records its current identity; guessing a migration could
+// grant access to a replacement sandbox that never selected that setup.
+export function sandboxSetups(members, sandbox, endpoint) {
+  const key = keyFor(endpoint, sandbox?.id)
+  return key ? ids(members[key]) : []
+}
+
+export function createSetupMembers(file = membersFile()) {
+  let edits = Promise.resolve()
+  async function read() {
+    let raw
+    try { raw = JSON.parse(await fs.readFile(file, 'utf8')) } catch (e) { if (e.code === 'ENOENT' || e instanceof SyntaxError) return {}; throw e }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {}
+    return Object.fromEntries(Object.entries(raw).filter(([key]) => storedKey(key)).map(([key, list]) => [key, ids(list)]).filter(([, list]) => list.length))
+  }
+  // Read-modify-write, one at a time; the file is replaced atomically.
+  const edit = (identity, change, { strict = true } = {}) => {
+    const run = edits.then(async () => {
+      const key = keyFor(identity?.gateway, identity?.id)
+      if (!NAME.test(String(identity?.name ?? '')) || !key) { if (strict) throw fail('Choose a sandbox identity with its gateway, id and name.'); return [] }
+      const all = await read()
+      const next = ids(change(all[key] ?? []))
+      if (JSON.stringify(next) === JSON.stringify(all[key] ?? [])) return next
+      if (next.length) all[key] = next
+      else delete all[key]
+      await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+      const temporary = `${file}.${randomUUID()}.tmp`
+      try {
+        await fs.writeFile(temporary, `${JSON.stringify(Object.fromEntries(Object.entries(all).sort(([a], [b]) => a.localeCompare(b))), null, 2)}\n`, { flag: 'wx', mode: 0o600 })
+        await fs.rename(temporary, file)
+      } finally { await fs.rm(temporary, { force: true }) }
+      return next
+    })
+    edits = run.catch(() => {})
+    return run
+  }
+  return {
+    readSetupMembers: read,
+    setSandboxSetups: (identity, list) => edit(identity, () => ids(list)),
+    addSandboxSetups: (identity, list) => edit(identity, (current) => [...current, ...ids(list)]),
+    removeSandboxSetups: (identity, list) => edit(identity, (current) => current.filter((id) => !ids(list).includes(id))),
+    forgetSandbox: (identity) => edit(identity, () => [], { strict: false }),
+  }
+}
+
+const stores = new Map()
+function setupMembers() {
+  const file = membersFile()
+  if (!stores.has(file)) stores.set(file, createSetupMembers(file))
+  return stores.get(file)
+}
+
+export const readSetupMembers = () => setupMembers().readSetupMembers()
+export const setSandboxSetups = (identity, list) => setupMembers().setSandboxSetups(identity, list)
+export const addSandboxSetups = (identity, list) => setupMembers().addSandboxSetups(identity, list)
+export const removeSandboxSetups = (identity, list) => setupMembers().removeSandboxSetups(identity, list)
+export const forgetSandbox = (identity) => setupMembers().forgetSandbox(identity)