windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/host/repo-guard.js

@@ -0,0 +1,219 @@
+// Zero-click protection for the folder the sandbox shares with this PC.
+//
+// The agent can write the workspace. Two kinds of change there would run code on THIS PC without you doing anything
+// unusual, so they are snapshotted before launch, re-checked every minute while the sandbox runs and when it closes,
+// and neutralised:
+//  - git: new or changed hooks, and config that makes git run programs (core.fsmonitor, core.sshCommand, filters,
+//    include.path, ...), plus files that redirect where git reads config and hooks (commondir, config.worktree);
+//  - commands: executables dropped in the project root under the name of something you type there (node.exe,
+//    git.cmd, npm.cmd, ...), because Windows runs a program from the current folder before searching PATH.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { z } from 'zod';
+import { readValid, writeFileAtomic, writeJsonAtomic } from '../shared/rundir.js';
+import { assertTestWritable } from './test-guard.js';
+import { dirExists, fileExists, isLink } from '../core/util.js';
+/** Config keys that make git run a program, or load more config. */
+const DANGEROUS_KEY = /^(fsmonitor|hookspath|sshcommand|pager|editor|askpass|program|gpgprogram|textconv|command|cmd|clean|smudge|process|driver|helper|uploadpack|receivepack|path|attributesfile|excludesfile|worktree|worktreeconfig|gitproxy|proxycommand|sendemailvalidate|tool)\s*=/i;
+const SECTION = /^\s*\[([^\]]*)\]\s*/;
+const MARK = '# [agent-sandbox] disabled, added inside the sandbox: ';
+/** Files in .git that make git read config/hooks from somewhere else. */
+const REDIRECTS = ['commondir', 'config.worktree'];
+/** Names you are likely to run in a project folder; with any of these extensions Windows would pick the local copy. */
+const COMMANDS = new RegExp('^(' + [
+    // this tool's own commands (package.json "bin")
+    'sandbox', 'windows-development-sandbox', 'agent-sandbox', 'claude-sbx', 'claude-sandbox', 'codex-sbx', 'codex-sandbox', 'gemini-sbx', 'gemini-sandbox', 'claude-host', 'sbx-show', 'sbx-hide',
+    // agents
+    'claude', 'codex', 'gemini', 'opencode', 'qwen', 'crush', 'copilot', 'kilo', 'kilocode', 'amp', 'cline', 'cn', 'kimi', 'reasonix', 'codewhale', 'aider', 'cursor-agent', 'agent', 'goose',
+    // toolchains and everyday tools
+    'node', 'npm', 'npx', 'pnpm', 'pnpx', 'yarn', 'corepack', 'volta', 'nvm', 'deno', 'bun', 'bunx', 'tsc', 'git', 'gh', 'code', 'python', 'python3', 'py', 'pip', 'pip3', 'uv', 'uvx', 'pyenv', 'poetry',
+    'cargo', 'rustc', 'rustup', 'dotnet', 'nuget', 'msbuild', 'go', 'java', 'javac', 'mvn', 'mvnw', 'gradle', 'gradlew', 'ruby', 'gem', 'bundle', 'rake', 'rails', 'php', 'composer',
+    'make', 'cmake', 'ninja', 'gcc', 'g\\+\\+', 'clang', 'psql', 'mysql', 'mariadb', 'mongosh', 'redis-cli', 'docker', 'kubectl', 'terraform', 'az', 'aws',
+    'powershell', 'pwsh', 'cmd', 'where', 'tasklist', 'tar', 'curl', 'ssh', 'scp',
+].join('|') + ')\\.(exe|com|bat|cmd|vbs|vbe|js|jse|wsf|wsh|msc|ps1)$', 'i');
+/** SHA-256 in small chunks: a sandbox can plant a multi-gigabyte "node.exe" to exhaust this PC's memory. */
+const hash = (file) => {
+    if (isLink(file))
+        return 'link';
+    const sum = crypto.createHash('sha256');
+    const buffer = Buffer.alloc(1 << 20);
+    let fd;
+    // A file that cannot be read (locked by a program in the sandbox) never matches the snapshot, so it is dealt with.
+    try {
+        fd = fs.openSync(file, 'r');
+    }
+    catch {
+        return 'unreadable-' + crypto.randomBytes(4).toString('hex');
+    }
+    try {
+        for (let n = fs.readSync(fd, buffer, 0, buffer.length, null); n > 0; n = fs.readSync(fd, buffer, 0, buffer.length, null))
+            sum.update(buffer.subarray(0, n));
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return sum.digest('hex');
+};
+const MAX_CONFIG_BYTES = 4 * 1024 * 1024;
+const plainGitDir = (workspace) => {
+    const dir = path.join(workspace, '.git');
+    return dirExists(dir) && !isLink(dir) ? dir : null;
+};
+const filesIn = (dir, accept) => dirExists(dir) && !isLink(dir)
+    ? Object.fromEntries(fs.readdirSync(dir, { withFileTypes: true }).filter((e) => (e.isFile() || e.isSymbolicLink()) && accept(e.name)).map((e) => [e.name, hash(path.join(dir, e.name))]))
+    : {};
+const configLines = (dir) => {
+    const file = path.join(dir, 'config');
+    return fileExists(file) && !isLink(file) && fs.statSync(file).size <= MAX_CONFIG_BYTES ? fs.readFileSync(file, 'utf8').split(/\r?\n/) : [];
+};
+export const snapshotRepo = (workspace) => {
+    const dir = plainGitDir(workspace);
+    return {
+        gitDir: dir !== null,
+        config: dir ? configLines(dir) : [],
+        hooks: dir ? filesIn(path.join(dir, 'hooks'), (n) => !n.endsWith('.sample')) : {},
+        redirects: dir ? REDIRECTS.filter((n) => fs.existsSync(path.join(dir, n))) : [],
+        commands: filesIn(workspace, (n) => COMMANDS.test(n)),
+    };
+};
+/** Moves files into <dir>\agent-sandbox-quarantine\<time>\ and reports them. */
+const quarantine = (from, names, into, kind) => {
+    if (names.length === 0)
+        return [];
+    const target = path.join(into, 'agent-sandbox-quarantine', String(Date.now()));
+    fs.mkdirSync(target, { recursive: true });
+    return names.map((name) => {
+        try {
+            fs.renameSync(path.join(from, name), path.join(target, name));
+        }
+        catch (e) {
+            return { kind, detail: name + ' (could not be moved: ' + e.code + '; delete it yourself before running anything here)' };
+        }
+        return { kind, detail: name + ' (moved to ' + target + ')' };
+    });
+};
+/** Comments out newly added config lines that make git run programs. Existing lines are never touched. */
+const disableConfig = (dir, before) => {
+    const lines = configLines(dir);
+    const known = _.countBy(before);
+    const seen = {};
+    const findings = [];
+    let inInclude = false;
+    const fixed = lines.map((line) => {
+        const header = SECTION.exec(line);
+        if (header)
+            inInclude = /^include(if\s+"[^"]*")?$/i.test(header[1].trim());
+        seen[line] = (seen[line] ?? 0) + 1;
+        if (line.startsWith(MARK) || seen[line] <= (known[line] ?? 0))
+            return line;
+        // git also accepts "[core] fsmonitor = x" on one line, so look past a leading section header.
+        const keyPart = line.replace(SECTION, '').trim();
+        if (!(DANGEROUS_KEY.test(keyPart) || (inInclude && keyPart.includes('='))))
+            return line;
+        findings.push({ kind: 'config', detail: line.trim() });
+        return MARK + line.trim();
+    });
+    if (findings.length)
+        writeFileAtomic(path.join(dir, 'config'), fixed.join('\n'));
+    const file = path.join(dir, 'config');
+    // A link or a huge file is not read at all, so say so instead of letting it pass as "nothing found".
+    const unchecked = isLink(file) ? '.git/config is a link' : lines.length === 0 && fileExists(file) && fs.statSync(file).size > MAX_CONFIG_BYTES ? '.git/config is over 4 MB' : null;
+    if (unchecked)
+        findings.push({ kind: 'git', detail: unchecked + ', so it cannot be checked. Do not run git in this folder until you have looked at it.' });
+    return findings;
+};
+/**
+ * Compares the workspace with its pre-launch snapshot and neutralises anything new that would execute on this PC.
+ * Returns what was found (and fixed). Never touches what was already there before the sandbox ran.
+ */
+export const guardRepo = (workspace, before) => {
+    assertTestWritable(workspace);
+    const findings = [];
+    const commandsNow = filesIn(workspace, (n) => COMMANDS.test(n));
+    findings.push(...quarantine(workspace, Object.keys(commandsNow).filter((n) => before.commands[n] !== commandsNow[n]), workspace, 'command'));
+    const dir = plainGitDir(workspace);
+    if (!dir) {
+        const replaced = before.gitDir && fs.existsSync(path.join(workspace, '.git'));
+        if (replaced)
+            findings.push({ kind: 'git', detail: '.git was replaced by a link or a "gitdir:" file inside the sandbox. Do not run git in ' + workspace + ' until you have checked it.' });
+        return findings;
+    }
+    const hooksDir = path.join(dir, 'hooks');
+    const hooksNow = filesIn(hooksDir, (n) => !n.endsWith('.sample'));
+    findings.push(...quarantine(hooksDir, Object.keys(hooksNow).filter((n) => before.hooks[n] !== hooksNow[n]), dir, 'hook'));
+    findings.push(...quarantine(dir, REDIRECTS.filter((n) => fs.existsSync(path.join(dir, n)) && !before.redirects.includes(n)), dir, 'git'));
+    findings.push(...disableConfig(dir, before.config));
+    return findings;
+};
+// ---- snapshot storage (host-only, next to the sync state) ---------------------------------------------------------
+const syncDir = (dataPath) => path.join(path.dirname(path.dirname(dataPath)), 'sync');
+const snapshotFile = (dataPath) => path.join(syncDir(dataPath), path.basename(dataPath) + '-repo.json');
+const findingsFile = (dataPath) => path.join(syncDir(dataPath), path.basename(dataPath) + '-repo-findings.json');
+const Finding = z.object({ kind: z.enum(['hook', 'config', 'git', 'command']), detail: z.string().max(4096), at: z.string().max(64).optional() });
+const Saved = z.object({
+    workspace: z.string().max(1024).refine((p) => path.isAbsolute(p)),
+    snapshot: z.object({ gitDir: z.boolean(), config: z.array(z.string()), hooks: z.record(z.string(), z.string()), redirects: z.array(z.string()), commands: z.record(z.string(), z.string()) }),
+});
+const Store = z.strictObject({ projects: z.array(Saved).max(4096), roots: z.array(z.string().max(1024).refine((p) => path.isAbsolute(p))).max(64) });
+const StoreAny = z.union([Store, Saved.transform((s) => ({ projects: [s], roots: [] }))]);
+const readStore = (dataPath) => readValid(StoreAny, snapshotFile(dataPath)) ?? { projects: [], roots: [] };
+const EMPTY = { gitDir: false, config: [], hooks: {}, redirects: [], commands: {} };
+const MAX_ROOT_PROJECTS = 2000;
+/** The folders directly inside a project root (plain folders only; links are never followed). */
+const rootProjects = (root) => {
+    if (!dirExists(root) || isLink(root))
+        return [];
+    return fs.readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.isSymbolicLink()).slice(0, MAX_ROOT_PROJECTS).map((e) => path.join(root, e.name));
+};
+const has = (projects, workspace) => projects.some((s) => s.workspace.toLowerCase() === workspace.toLowerCase());
+/**
+ * At launch: every folder the sandbox will be able to write. The launch folder, projects mapped with it and every
+ * project already inside a project root are snapshotted as they are now, before the sandbox can touch them.
+ */
+export const saveRepoSnapshot = (dataPath, workspace, more = [], roots = []) => {
+    const folders = _.uniqBy([workspace, ...more, ...roots.flatMap((r) => [r, ...rootProjects(r)])], (w) => w.toLowerCase());
+    writeJsonAtomic(snapshotFile(dataPath), { projects: folders.map((w) => ({ workspace: w, snapshot: snapshotRepo(w) })), roots });
+};
+/**
+ * A project that joins the running sandbox: snapshotted before its first session, then guarded like the launch
+ * folder. A project already guarded keeps its first snapshot (what was there before the sandbox could touch it).
+ */
+export const addRepoSnapshot = (dataPath, workspace, o = {}) => {
+    const store = readStore(dataPath);
+    // A folder inside one that is guarded already is covered by it only for its root files; it gets its own entry.
+    if (has(store.projects, workspace))
+        return;
+    writeJsonAtomic(snapshotFile(dataPath), { ...store, projects: [...store.projects, { workspace, snapshot: o.empty ? EMPTY : snapshotRepo(workspace) }] });
+};
+/**
+ * Folders that appeared inside a project root after the launch: the sandbox could have written them from the start,
+ * so they get an EMPTY baseline: any git hook, git config that runs programs (core.hooksPath, core.fsmonitor, ...)
+ * or planted command in them counts as added inside the sandbox and is neutralised.
+ */
+const discoverRootProjects = (dataPath) => {
+    const store = readStore(dataPath);
+    const found = store.roots.flatMap(rootProjects).filter((w) => !has(store.projects, w)).map((workspace) => ({ workspace, snapshot: EMPTY }));
+    if (!found.length)
+        return store.projects;
+    const projects = [...store.projects, ...found].slice(0, 4096);
+    writeJsonAtomic(snapshotFile(dataPath), { ...store, projects });
+    return projects;
+};
+/** The folders being guarded (for status). */
+export const guardedProjects = (dataPath) => readStore(dataPath).projects.map((s) => s.workspace);
+/** Re-checks every project of the current/last launch; findings are kept in a host-only file for `status`. Returns the new ones. */
+export const checkRepo = (dataPath) => {
+    const saved = discoverRootProjects(dataPath);
+    if (!saved.length)
+        return [];
+    const old = repoFindings(dataPath);
+    // A finding that cannot be fixed (a file locked in the sandbox) is reported once, not every minute.
+    const findings = saved.flatMap((s) => guardRepo(s.workspace, s.snapshot).map((f) => (saved.length > 1 ? { ...f, detail: s.workspace + ': ' + f.detail } : f)))
+        .filter((f) => !old.some((o) => o.kind === f.kind && o.detail === f.detail));
+    if (findings.length)
+        writeJsonAtomic(findingsFile(dataPath), [...old, ...findings.map((f) => ({ ...f, at: new Date().toISOString() }))]);
+    return findings;
+};
+export const repoFindings = (dataPath) => readValid(z.array(Finding).max(10000), findingsFile(dataPath)) ?? [];

package/dist/host/secrets.d.ts

@@ -0,0 +1,14 @@
+import type { Config } from '../core/types.js';
+export type SecretsConfig = Config['secrets'];
+export declare const isSecretName: (name: string, secrets: SecretsConfig) => boolean;
+export declare const isSecretValue: (value: string) => boolean;
+/** Whether a variable (name and value) may go into the sandbox. secrets.allow always wins. */
+export declare const mayPass: (name: string, value: unknown, secrets: SecretsConfig) => boolean;
+/** A copy of an env/headers map without the secrets; the names removed are added to `removed` (with `where`). */
+export declare const stripVariables: (vars: unknown, secrets: SecretsConfig, where: string, removed: string[]) => unknown;
+/** settings.json for the sandbox: secrets out of "env", credential helper commands removed. */
+export declare const stripSettings: (settings: Record<string, unknown>, secrets: SecretsConfig, removed: string[]) => Record<string, unknown>;
+/** Every MCP server in a .claude.json-shaped object (top level and per project). */
+export declare const stripMcpServers: (state: Record<string, unknown>, secrets: SecretsConfig, removed: string[]) => Record<string, unknown>;
+/** Secret-looking files in the workspace root and one folder down (skipping dependency folders). */
+export declare const findSecretFiles: (workspace: string) => string[];

package/dist/host/secrets.js

@@ -0,0 +1,133 @@
+// Keeps credentials on this PC. Everything copied into the sandbox from your Claude settings (settings.json "env",
+// MCP servers' env / headers / args in .claude.json) goes through here first: cloud and production credentials are
+// removed unless you let them through with secrets.allow. Pure functions, so they are easy to test.
+import fs from 'node:fs';
+import path from 'node:path';
+/** Variable names that are credentials by definition: cloud providers, hosting, CI, registries, payment, AI APIs, ... */
+const SECRET_NAMES = [
+    /^AWS_/, /^AMAZON_/, /^AZURE_/, /^ARM_(CLIENT|TENANT|SUBSCRIPTION|ACCESS)_/, /^MSAL_/, /^CLOUDFLARE_/, /^CF_(API|ACCOUNT|ZONE|ACCESS)/,
+    /^GOOGLE_(APPLICATION_CREDENTIALS|API_KEY|CLOUD_|CLIENT_SECRET)/, /^GCP_/, /^GCLOUD_/, /^GOOGLE_GHA_/, /^FIREBASE_/,
+    /^DIGITALOCEAN_/, /^DO_(API|AUTH)_/, /^LINODE_/, /^HCLOUD_/, /^OCI_/, /^ALIBABA_CLOUD_/, /^ALICLOUD_/, /^IBMCLOUD_/,
+    /^HEROKU_/, /^VERCEL_/, /^NETLIFY_/, /^RENDER_API/, /^FLY_(API|ACCESS)_/, /^RAILWAY_/, /^SUPABASE_/, /^NEON_/, /^PLANETSCALE_/,
+    /^GITHUB_TOKEN$/, /^GH_TOKEN$/, /^GH_ENTERPRISE_TOKEN$/, /^GITHUB_PAT/, /^GITLAB_/, /^BITBUCKET_/, /^CIRCLE_TOKEN$/, /^TRAVIS_/, /^BUILDKITE_/,
+    /^NPM_TOKEN$/, /^NODE_AUTH_TOKEN$/, /^YARN_NPM_AUTH/, /^NUGET_(API_KEY|AUTH)/, /^PYPI_/, /^TWINE_/, /^CARGO_REGISTRY_TOKEN$/, /^GEM_HOST_API_KEY$/,
+    /^DOCKER_(PASSWORD|TOKEN|AUTH)/, /^REGISTRY_(PASSWORD|TOKEN)/, /^KUBECONFIG$/, /^KUBE_TOKEN$/, /^HELM_/, /^VAULT_/, /^CONSUL_HTTP_TOKEN$/, /^NOMAD_TOKEN$/,
+    /^TF_VAR_/, /^TF_TOKEN_/, /^TFE_TOKEN$/, /^PULUMI_ACCESS_TOKEN$/, /^SPACELIFT_/, /^ANSIBLE_VAULT/,
+    /^STRIPE_/, /^PAYPAL_/, /^BRAINTREE_/, /^SQUARE_/, /^ADYEN_/, /^TWILIO_/, /^SENDGRID_/, /^MAILGUN_/, /^POSTMARK_/, /^MAILCHIMP_/, /^RESEND_/,
+    /^SLACK_/, /^DISCORD_(TOKEN|BOT|WEBHOOK)/, /^TELEGRAM_BOT/, /^SENTRY_(AUTH|DSN)/, /^DATADOG_/, /^DD_(API|APP)_KEY$/, /^NEW_RELIC_/, /^HONEYCOMB_/,
+    /^OPENAI_/, /^ANTHROPIC_(API_KEY|AUTH_TOKEN)$/, /^CLAUDE_CODE_OAUTH_TOKEN$/, /^GEMINI_API_KEY$/, /^MISTRAL_API_KEY$/, /^COHERE_API_KEY$/,
+    /^GROQ_API_KEY$/, /^HF_TOKEN$/, /^HUGGING_?FACE_/, /^REPLICATE_API/, /^PINECONE_/, /^ELEVENLABS_/,
+    /^DATABASE_URL$/, /^.*_DATABASE_URL$/, /^(PG|POSTGRES|MYSQL|MARIADB|MSSQL|MONGO(DB)?|REDIS|ELASTIC(SEARCH)?|RABBITMQ|SNOWFLAKE|DATABRICKS)_/,
+    /^SSH_AUTH_SOCK$/, /^GPG_/, /^OP_(SERVICE_ACCOUNT|CONNECT)_/, /^BWS_ACCESS_TOKEN$/, /^DOPPLER_/, /^INFISICAL_/,
+];
+/** Any name that says what it holds: ..._TOKEN, ..._SECRET, PASSWORD, API_KEY, ..._PRIVATE_KEY, connection strings, ... */
+const SECRET_WORDS = /(^|_)(PROD|PRODUCTION|LIVE|SECRETS?|TOKENS?|PASSWORDS?|PASSWD|PWD|PASS|API_?KEYS?|ACCESS_?KEYS?|PRIVATE_?KEYS?|SIGNING_?KEYS?|CREDENTIALS?|CREDS|AUTH|AUTHORIZATION|BEARER|COOKIES?|SESSION_?KEYS?|CONN(ECTION)?_?STR(ING)?|DSN|WEBHOOK(_URL)?|CLIENT_?SECRET|SAS|SALT|PAT)(_|$)/;
+/** Values that are credentials whatever they are called. */
+const SECRET_VALUES = [
+    /\b(AKIA|ASIA|AGPA|AIDA|AROA)[0-9A-Z]{16}\b/, // AWS access key ids
+    /\bgh[pousr]_[A-Za-z0-9]{30,}/, /\bgithub_pat_[A-Za-z0-9_]{40,}/, /\bglpat-[A-Za-z0-9_-]{20,}/,
+    /\bxox[abposr]-[A-Za-z0-9-]{10,}/, /\bsk-(ant-|proj-|live_|test_)?[A-Za-z0-9_-]{20,}/, /\b[rs]k_live_[A-Za-z0-9]{20,}/,
+    /\bAIza[0-9A-Za-z_-]{35}\b/, /\bya29\.[0-9A-Za-z_-]{20,}/, /\bnpm_[A-Za-z0-9]{36}\b/, /\bhf_[A-Za-z0-9]{30,}/,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/, /AccountKey=[A-Za-z0-9+/=]{20,}/i, /SharedAccessSignature=|[?&]sig=[A-Za-z0-9%+/=]{20,}/i,
+    /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s@/]+@/i, // user:password@host in any URL (database URLs, registries)
+    /\bBearer\s+\S{16,}/i, /\bBasic\s+[A-Za-z0-9+/=]{12,}/i,
+    /[?&](api[_-]?key|apikey|access[_-]?token|token|key|secret|password|sig|signature|auth)=[^&\s]{8,}/i, // credentials in a URL
+    /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, // JWTs
+];
+/** "AWS_REGION", "MY_*", "*_URL": * matches anything. Case-insensitive, like Windows variable names. */
+const globMatch = (pattern, name) => new RegExp('^' + pattern.split('*').map((p) => p.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$', 'i').test(name);
+export const isSecretName = (name, secrets) => {
+    // X-API-Key, x-auth-token, api.key: compared as X_API_KEY, X_AUTH_TOKEN, API_KEY.
+    const upper = name.toUpperCase().replace(/[-\s.]/g, '_');
+    return SECRET_NAMES.some((r) => r.test(upper)) || SECRET_WORDS.test(upper) || secrets.patterns.some((p) => globMatch(p, name));
+};
+export const isSecretValue = (value) => SECRET_VALUES.some((r) => r.test(value));
+/** Whether a variable (name and value) may go into the sandbox. secrets.allow always wins. */
+export const mayPass = (name, value, secrets) => {
+    if (!secrets.strip || secrets.allow.some((p) => globMatch(p, name)))
+        return true;
+    return !isSecretName(name, secrets) && !(typeof value === 'string' && isSecretValue(value));
+};
+/** A copy of an env/headers map without the secrets; the names removed are added to `removed` (with `where`). */
+export const stripVariables = (vars, secrets, where, removed) => {
+    if (typeof vars !== 'object' || vars === null || Array.isArray(vars))
+        return vars;
+    return Object.fromEntries(Object.entries(vars).filter(([name, value]) => {
+        const ok = mayPass(name, value, secrets);
+        if (!ok)
+            removed.push(where + name);
+        return ok;
+    }));
+};
+/** Claude settings keys that run commands to fetch credentials on this PC (they cannot work in the sandbox anyway). */
+const CREDENTIAL_HELPERS = ['apiKeyHelper', 'awsAuthRefresh', 'awsCredentialExport', 'otelHeadersHelper'];
+/** settings.json for the sandbox: secrets out of "env", credential helper commands removed. */
+export const stripSettings = (settings, secrets, removed) => {
+    if (!secrets.strip)
+        return settings;
+    const out = { ...settings };
+    for (const key of CREDENTIAL_HELPERS.filter((k) => k in out)) {
+        delete out[key];
+        removed.push('settings.json ' + key);
+    }
+    if ('env' in out)
+        out.env = stripVariables(out.env, secrets, 'settings.json env.', removed);
+    return out;
+};
+/** One MCP server: secret env vars and headers removed, and secret-looking command-line arguments blanked. */
+const stripServer = (server, secrets, where, removed) => {
+    if (typeof server !== 'object' || server === null)
+        return server;
+    const out = { ...server };
+    if ('env' in out)
+        out.env = stripVariables(out.env, secrets, where + ' env.', removed);
+    if ('headers' in out)
+        out.headers = stripVariables(out.headers, secrets, where + ' header ', removed);
+    if (typeof out.url === 'string' && secrets.strip && isSecretValue(out.url)) {
+        removed.push(where + ' url (it carried a credential)');
+        out.url = out.url.replace(/([?&])[^=&#]+=[^&#]*/g, (m, sep) => (isSecretValue('?' + m.slice(1)) ? sep + m.slice(1).split('=')[0] + '=REMOVED' : m));
+    }
+    if (Array.isArray(out.args) && secrets.strip) {
+        out.args = out.args.map((arg, i) => {
+            const previous = i > 0 ? String(out.args[i - 1]) : '';
+            const [flag, inline] = typeof arg === 'string' && /^--?[\w-]+=/.test(arg) ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [null, null];
+            const secretFlag = (f) => /^--?[\w-]+$/.test(f) && isSecretName(f.replace(/^-+/, ''), secrets);
+            const flagged = typeof arg === 'string' && (isSecretValue(arg) || (flag !== null && (secretFlag(flag) || isSecretValue(inline))) || secretFlag(previous));
+            if (flagged)
+                removed.push(where + ' argument ' + (i + 1));
+            return flagged ? '[removed by agent-sandbox]' : arg;
+        });
+    }
+    return out;
+};
+/** Every MCP server in a .claude.json-shaped object (top level and per project). */
+export const stripMcpServers = (state, secrets, removed) => {
+    if (!secrets.strip)
+        return state;
+    const servers = (owner, where) => {
+        const list = owner.mcpServers;
+        if (typeof list !== 'object' || list === null)
+            return owner;
+        return { ...owner, mcpServers: Object.fromEntries(Object.entries(list).map(([name, s]) => [name, stripServer(s, secrets, where + 'MCP ' + name, removed)])) };
+    };
+    const top = servers(state, '');
+    const projects = top.projects;
+    return projects ? { ...top, projects: Object.fromEntries(Object.entries(projects).map(([key, p]) => [key, servers(p, '')])) } : top;
+};
+/** Files in the workspace that usually hold secrets. The agent CAN read them (the whole folder is mapped); we only warn. */
+const SECRET_FILES = /^(\.env(\..+)?|\.envrc|.*\.(pem|key|p12|pfx|jks|keystore|kdbx|tfvars|ovpn)|credentials(\.json)?|secrets?\.(json|ya?ml|toml)|service[-_]?account.*\.json|id_(rsa|ed25519|ecdsa)|\.npmrc|\.pypirc|\.netrc|\.git-credentials)$/i;
+const TEMPLATE = /\.(example|sample|template|dist|defaults?)$/i;
+/** Secret-looking files in the workspace root and one folder down (skipping dependency folders). */
+export const findSecretFiles = (workspace) => {
+    const list = (dir) => { try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    } };
+    const hit = (name) => SECRET_FILES.test(name) && !TEMPLATE.test(name);
+    const top = list(workspace);
+    const below = top.filter((d) => d.isDirectory() && !/^(node_modules|\.git|vendor|target|dist|build|\.venv|venv)$/i.test(d.name))
+        .flatMap((d) => list(path.join(workspace, d.name)).filter((f) => f.isFile() && hit(f.name)).map((f) => d.name + '\\' + f.name));
+    return [...top.filter((d) => d.isFile() && hit(d.name)).map((d) => d.name), ...below];
+};

package/dist/host/terminal.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export declare const terminalDir: (dataPath: string) => string;
+export declare const terminalExe: (dataPath: string) => string;
+/** Our own profile id, so the profile is found again (and user edits to it are kept) on later launches. */
+export declare const PWSH_PROFILE_GUID = "{5f3a6c1e-7d2b-4e8a-9c41-0b6d2a8f7e93}";
+declare const TerminalSettings: z.ZodObject<{
+    profiles: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+        guid: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>, z.ZodObject<{
+        list: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            guid: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>]>>;
+}, z.core.$loose>;
+/**
+ * settings.json with the "PowerShell 7" profile shown when `visible`, else hidden (never deleted: a user's tweaks to it
+ * survive turning pwsh off and on). Pure: returns null when nothing changes.
+ */
+export declare const withPwshProfile: (settings: z.output<typeof TerminalSettings>, visible: boolean) => z.output<typeof TerminalSettings> | null;
+/**
+ * Shows the PowerShell 7 profile once pwsh is installed in this data folder (and `allowed`, i.e. toolchains.pwsh is
+ * not off), hides it otherwise. settings.json is written by the sandbox too: read with a size cap, through no links,
+ * shape-checked, only rewritten when the profile changes; a file that does not parse is left alone.
+ */
+export declare const syncPwshProfile: (dataPath: string, allowed: boolean) => void;
+export declare const ensureTerminal: (dataPath: string, refresh: boolean, options?: {
+    pwsh?: boolean;
+}) => Promise<{
+    exe: string | null;
+    message: string;
+}>;
+export {};

package/dist/host/terminal.js

@@ -0,0 +1,130 @@
+// Windows Terminal for the sandbox window. The host downloads the portable build once into persistent storage, so
+// logon.cmd can open it the moment the sandbox logs in (no PowerShell window first).
+import fs from 'node:fs';
+import path from 'node:path';
+import { githubAsset, installArchive } from '../shared/download.js';
+import { safeRemove } from '../shared/safe-remove.js';
+import { assertTestWritable } from './test-guard.js';
+import { z } from 'zod';
+import { assertNoLinks, errMsg, fileExists, parseJsonc, writeJson } from '../core/util.js';
+export const terminalDir = (dataPath) => path.join(dataPath, 'tools', 'terminal');
+export const terminalExe = (dataPath) => path.join(terminalDir(dataPath), 'WindowsTerminal.exe');
+/**
+ * Sandbox-friendly defaults; only written when there is no settings.json yet (first download), so edits made inside
+ * the sandbox stick, also across a refresh (which keeps the settings folder).
+ */
+const SETTINGS = {
+    $schema: 'https://aka.ms/terminal-profiles-schema',
+    theme: 'dark',
+    firstWindowPreference: 'defaultProfile',
+    confirmCloseAllTabs: false,
+    // New tabs pick up the PATH and variables the runner writes machine-wide after the window opened.
+    compatibility: { reloadEnvironmentVariables: true },
+    warning: { confirmCloseAllTabs: false, largePaste: false, multiLinePaste: false },
+    profiles: { defaults: { font: { face: 'Cascadia Mono' }, startingDirectory: '%AGENT_WORKSPACE%', closeOnExit: 'graceful' } },
+};
+/** Our own profile id, so the profile is found again (and user edits to it are kept) on later launches. */
+export const PWSH_PROFILE_GUID = '{5f3a6c1e-7d2b-4e8a-9c41-0b6d2a8f7e93}';
+/** pwsh.exe as the sandbox sees it (toolchains/pwsh.ts installs it to tools\pwsh). */
+const GUEST_PWSH = 'C:\\AgentData\\tools\\pwsh\\pwsh.exe';
+const MAX_SETTINGS_BYTES = 1024 * 1024;
+const TerminalSettings = z.looseObject({
+    profiles: z.union([z.array(z.looseObject({ guid: z.string().optional() })), z.looseObject({ list: z.array(z.looseObject({ guid: z.string().optional() })).optional() })]).optional(),
+});
+/**
+ * settings.json with the "PowerShell 7" profile shown when `visible`, else hidden (never deleted: a user's tweaks to it
+ * survive turning pwsh off and on). Pure: returns null when nothing changes.
+ */
+export const withPwshProfile = (settings, visible) => {
+    const profiles = Array.isArray(settings.profiles) ? { list: settings.profiles } : { ...settings.profiles };
+    const list = [...(profiles.list ?? [])];
+    const at = list.findIndex((p) => p.guid?.toLowerCase() === PWSH_PROFILE_GUID);
+    if (at === -1 && !visible)
+        return null;
+    if (at === -1)
+        list.push({ guid: PWSH_PROFILE_GUID, name: 'PowerShell 7', commandline: '"' + GUEST_PWSH + '" -NoLogo', icon: GUEST_PWSH, hidden: false });
+    else if ((list[at].hidden === true) === !visible)
+        return null;
+    else
+        list[at] = { ...list[at], hidden: !visible };
+    return { ...settings, profiles: { ...profiles, list } };
+};
+/**
+ * Shows the PowerShell 7 profile once pwsh is installed in this data folder (and `allowed`, i.e. toolchains.pwsh is
+ * not off), hides it otherwise. settings.json is written by the sandbox too: read with a size cap, through no links,
+ * shape-checked, only rewritten when the profile changes; a file that does not parse is left alone.
+ */
+export const syncPwshProfile = (dataPath, allowed) => {
+    const file = path.join(terminalDir(dataPath), 'settings', 'settings.json');
+    assertTestWritable(file);
+    assertNoLinks(dataPath, file);
+    if (!fileExists(file) || fs.statSync(file).size > MAX_SETTINGS_BYTES)
+        return;
+    const visible = allowed && fileExists(path.join(dataPath, 'tools', 'pwsh', 'pwsh.exe'));
+    let parsed;
+    try {
+        const result = TerminalSettings.safeParse(parseJsonc(fs.readFileSync(file, 'utf8'), file));
+        if (!result.success)
+            return;
+        parsed = result.data;
+    }
+    catch {
+        return;
+    }
+    const next = withPwshProfile(parsed, visible);
+    if (next)
+        writeJson(file, next);
+};
+export const ensureTerminal = async (dataPath, refresh, options = {}) => {
+    const result = await installTerminal(dataPath, refresh);
+    if (result.exe) {
+        // The profile is a nicety: a settings problem never costs the sandbox its terminal.
+        try {
+            syncPwshProfile(dataPath, options.pwsh ?? false);
+        }
+        catch (e) {
+            return { ...result, message: result.message + ' (PowerShell 7 profile not updated: ' + errMsg(e) + ')' };
+        }
+    }
+    return result;
+};
+const installTerminal = async (dataPath, refresh) => {
+    const exe = terminalExe(dataPath);
+    const dir = terminalDir(dataPath);
+    assertTestWritable(dir);
+    const settings = path.join(dir, 'settings');
+    // installArchive replaces tools\terminal: the portable settings folder waits here meanwhile (and goes back also when
+    // the download fails). One still parked from an interrupted earlier run is the one to keep.
+    const parked = path.join(dataPath, 'tools', 'terminal-settings.parked');
+    assertNoLinks(dataPath, settings);
+    assertNoLinks(dataPath, parked);
+    if (fileExists(exe) && !refresh)
+        return { exe, message: 'cached' };
+    try {
+        if (fs.existsSync(settings)) {
+            safeRemove(parked, path.dirname(parked));
+            fs.renameSync(settings, parked);
+        }
+        try {
+            const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+            const asset = await githubAsset('microsoft/terminal', new RegExp('^Microsoft\\.WindowsTerminal_[\\d.]+_' + arch + '\\.zip$'));
+            await installArchive(asset.url, dir, { sha256: asset.sha256, locate: 'WindowsTerminal.exe', fileName: asset.name });
+            fs.writeFileSync(path.join(dir, '.portable'), '');
+            return { exe, message: 'downloaded ' + asset.name };
+        }
+        finally {
+            if (fs.existsSync(parked)) {
+                fs.mkdirSync(dir, { recursive: true });
+                safeRemove(settings, path.dirname(settings));
+                fs.renameSync(parked, settings);
+            }
+            const settingsFile = path.join(settings, 'settings.json');
+            assertNoLinks(dataPath, settingsFile);
+            if (fileExists(path.join(dir, '.portable')) && !fs.existsSync(settingsFile))
+                writeJson(settingsFile, SETTINGS);
+        }
+    }
+    catch (e) {
+        return { exe: null, message: 'download failed, the sandbox will use a plain PowerShell window (' + errMsg(e) + ')' };
+    }
+};

package/dist/host/test-guard.d.ts

@@ -0,0 +1,6 @@
+import { selfTestRunning } from '../shared/test-guard.js';
+export { selfTestRunning };
+/** Refuses an action that reaches outside the test's own temp folder (a no-op outside the self-test). */
+export declare const refuseInSelfTest: (what: string) => void;
+/** A write, copy or delete on the host: during the self-test only the temp folder is allowed. */
+export declare const assertTestWritable: (target: string) => void;

package/dist/host/test-guard.js

@@ -0,0 +1,15 @@
+// Host side of the self-test guard (see shared/test-guard.ts): outward actions refuse, with a message the user can read.
+import { testWriteRefusal, selfTestRunning } from '../shared/test-guard.js';
+import { fail } from '../core/util.js';
+export { selfTestRunning };
+/** Refuses an action that reaches outside the test's own temp folder (a no-op outside the self-test). */
+export const refuseInSelfTest = (what) => {
+    if (selfTestRunning())
+        fail('The self-test does not ' + what + '.', 'It only works in temp folders, so it can never change this PC.');
+};
+/** A write, copy or delete on the host: during the self-test only the temp folder is allowed. */
+export const assertTestWritable = (target) => {
+    const refusal = testWriteRefusal(target);
+    if (refusal)
+        fail(refusal);
+};

package/dist/host/window.d.ts

@@ -0,0 +1,4 @@
+/** Waits for the sandbox window and hides it; keeps watching briefly in case Windows re-shows it while connecting. */
+export declare const hideSandboxWindow: (storageRoot: string, waitSeconds?: number) => Promise<boolean>;
+/** Shows the sandbox window again (the ones we hid, or any hidden Windows Sandbox window). */
+export declare const showSandboxWindow: (storageRoot: string) => boolean;

package/dist/host/window.js

@@ -0,0 +1,72 @@
+// Headless mode: Windows Sandbox always opens its client window, so we hide it (ShowWindow SW_HIDE) as soon as it
+// appears. The VM and the logged-in session keep running; `sbx-show` brings the window back.
+import path from 'node:path';
+import { writeJsonAtomic } from '../shared/rundir.js';
+import { refuseInSelfTest } from './test-guard.js';
+import { isWin, runPowerShell, runPowerShellAsync, tryReadJson } from '../core/util.js';
+const PRELUDE = `
+$ErrorActionPreference = 'Stop'
+Add-Type -Namespace AgentSandbox -Name Win -MemberDefinition @'
+public delegate bool EnumProc(System.IntPtr hWnd, System.IntPtr lParam);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool EnumWindows(EnumProc cb, System.IntPtr lParam);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(System.IntPtr hWnd, out uint pid);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool IsWindowVisible(System.IntPtr hWnd);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool IsWindow(System.IntPtr hWnd);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern System.IntPtr GetWindow(System.IntPtr hWnd, uint cmd);
+[System.Runtime.InteropServices.DllImport("user32.dll", CharSet = System.Runtime.InteropServices.CharSet.Unicode)] public static extern int GetWindowText(System.IntPtr hWnd, System.Text.StringBuilder s, int n);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool ShowWindow(System.IntPtr hWnd, int cmd);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool SetForegroundWindow(System.IntPtr hWnd);
+'@
+function Get-SandboxWindows([bool]$visibleOnly) {
+  $pids = @(Get-Process | Where-Object { $_.ProcessName -like 'WindowsSandbox*' } | ForEach-Object { [uint32]$_.Id })
+  $found = New-Object System.Collections.ArrayList
+  if ($pids.Count -eq 0) { return $found }
+  $cb = [AgentSandbox.Win+EnumProc]{ param($h, $l)
+    $p = [uint32]0; [void][AgentSandbox.Win]::GetWindowThreadProcessId($h, [ref]$p)
+    if ($pids -contains $p -and [AgentSandbox.Win]::GetWindow($h, 4) -eq [IntPtr]::Zero) {
+      $sb = New-Object System.Text.StringBuilder 256; [void][AgentSandbox.Win]::GetWindowText($h, $sb, 256)
+      $title = $sb.ToString()
+      if ($title -like '*Sandbox*' -and (-not $visibleOnly -or [AgentSandbox.Win]::IsWindowVisible($h))) { [void]$found.Add([int64]$h) }
+    }
+    return $true }
+  [void][AgentSandbox.Win]::EnumWindows($cb, [IntPtr]::Zero)
+  return $found
+}
+`;
+const stateFile = (storageRoot) => path.join(storageRoot, 'run', 'hidden-windows.json');
+/** Waits for the sandbox window and hides it; keeps watching briefly in case Windows re-shows it while connecting. */
+export const hideSandboxWindow = async (storageRoot, waitSeconds = 180) => {
+    refuseInSelfTest('hide windows');
+    if (!isWin)
+        return false;
+    const script = PRELUDE + `
+$hidden = New-Object System.Collections.ArrayList
+$deadline = (Get-Date).AddSeconds(${waitSeconds}); $settle = $null
+while ((Get-Date) -lt $deadline) {
+  foreach ($h in (Get-SandboxWindows $true)) { [void][AgentSandbox.Win]::ShowWindow([IntPtr]$h, 0); if (-not $hidden.Contains($h)) { [void]$hidden.Add($h) } }
+  if ($hidden.Count -gt 0 -and $null -eq $settle) { $settle = (Get-Date).AddSeconds(15) }
+  if ($null -ne $settle -and (Get-Date) -gt $settle) { break }
+  Start-Sleep -Milliseconds 200
+}
+ConvertTo-Json -Compress @($hidden)`;
+    const stdout = await runPowerShellAsync(script);
+    const handles = JSON.parse(stdout.trim() || '[]').filter((h) => Number.isSafeInteger(h));
+    writeJsonAtomic(stateFile(storageRoot), { handles });
+    return handles.length > 0;
+};
+/** Shows the sandbox window again (the ones we hid, or any hidden Windows Sandbox window). */
+export const showSandboxWindow = (storageRoot) => {
+    refuseInSelfTest('show windows');
+    if (!isWin)
+        return false;
+    // Only integers go into the script, whatever the file contains.
+    const recorded = (tryReadJson(stateFile(storageRoot))?.handles ?? []).filter((h) => Number.isSafeInteger(h));
+    const script = PRELUDE + `
+$handles = @(${recorded.join(',')}) | Where-Object { [AgentSandbox.Win]::IsWindow([IntPtr]$_) }
+if (-not $handles) { $handles = Get-SandboxWindows $false }
+foreach ($h in $handles) { [void][AgentSandbox.Win]::ShowWindow([IntPtr]$h, 5); [void][AgentSandbox.Win]::ShowWindow([IntPtr]$h, 9); [void][AgentSandbox.Win]::SetForegroundWindow([IntPtr]$h) }
+@($handles).Count`;
+    const { stdout } = runPowerShell(script, true);
+    writeJsonAtomic(stateFile(storageRoot), { handles: [] });
+    return Number(stdout.trim()) > 0;
+};