feat(apps): scope process.env to a from-scratch allowlist during local execution

Milestone 8 (Secret Store parity). Without this, a customer's backend
function reads the dev server's own real process.env with no
restriction at all — leaking the developer's entire shell (AWS
credentials, other API keys, the dev server's own DD_API_KEY/DD_APP_KEY)
into arbitrary, possibly third-party code. Production has no equivalent
gap: each execution gets a fresh Deno subprocess with --allow-env scoped
to exactly the resolved credential names; in-process local execution has
no process boundary to rely on, so this closes the gap at the module
level instead, mirroring network-guard.ts's monkey-patch approach and
reusing the same shared generation-counter protection against the same
abandoned-execution race class.

Also blocks reads of /proc/self/environ (and /proc/<pid>/environ) while
a scoped-env window is active: swapping the JS-level process.env object
alone isn't a real boundary on Linux, since that kernel-backed file
exposes the process's real startup environment unaffected by
reassigning process.env.

Custom Credentials resolution (e.g. STRIPE_API_KEY) remains an open,
undecided question — buildScopedEnv's customCredentials parameter is a
forward-looking extension point, always {} for now.

Author: tyffical

packages/plugins/apps/src/vite/env-guard.test.ts

@@ -0,0 +1,247 @@
+// Unless explicitly stated otherwise all files in this repository are licensed under the MIT License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2019-Present Datadog, Inc.
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { buildScopedEnv, forceResetEnv, runWithScopedEnv } from './env-guard';
+
+/**
+ * Hard backstop, independent of whatever a given test's own assertions do:
+ * `process.env` is a real, process-wide singleton, not per-test-file
+ * sandboxed state — a test that leaves it swapped (e.g. a bug in one of
+ * these tests that skips its own restore) would otherwise leak into every
+ * test that runs afterward in the same Jest worker, including completely
+ * unrelated test files elsewhere in the suite.
+ */
+afterEach(() => {
+    forceResetEnv();
+});
+
+describe('env-guard', () => {
+    describe('buildScopedEnv', () => {
+        const originalEnv = process.env;
+
+        afterEach(() => {
+            process.env = originalEnv;
+        });
+
+        test('Should include only the safe allowlisted keys from the real environment, dropping everything else', () => {
+            process.env = {
+                PATH: '/usr/bin',
+                HOME: '/home/dev',
+                NODE_ENV: 'development',
+                TMPDIR: '/tmp',
+                AWS_SECRET_ACCESS_KEY: 'super-secret-aws-key',
+                DD_API_KEY: 'the-dev-servers-own-api-key',
+                SOME_RANDOM_SHELL_VAR: 'whatever',
+            };
+
+            const scoped = buildScopedEnv({});
+
+            expect(scoped).toEqual({
+                PATH: '/usr/bin',
+                HOME: '/home/dev',
+                NODE_ENV: 'development',
+                TMPDIR: '/tmp',
+            });
+        });
+
+        test('Should merge in the provided Custom Credentials under their own names', () => {
+            process.env = { PATH: '/usr/bin' };
+
+            const scoped = buildScopedEnv({ STRIPE_API_KEY: 'sk_test_123' });
+
+            expect(scoped).toEqual({ PATH: '/usr/bin', STRIPE_API_KEY: 'sk_test_123' });
+        });
+
+        test('Should omit an allowlisted key entirely when unset in the real environment, rather than including it as undefined', () => {
+            process.env = { PATH: '/usr/bin' };
+
+            const scoped = buildScopedEnv({});
+
+            expect('HOME' in scoped).toBe(false);
+            expect('NODE_ENV' in scoped).toBe(false);
+            expect('TMPDIR' in scoped).toBe(false);
+        });
+    });
+
+    describe('runWithScopedEnv', () => {
+        test('Should expose only the scoped env to fn, not the real process.env', async () => {
+            const scoped = { PATH: '/usr/bin', STRIPE_API_KEY: 'sk_test_123' };
+
+            const seenKeys = await runWithScopedEnv(scoped, async () => Object.keys(process.env));
+
+            expect(seenKeys.sort()).toEqual(['PATH', 'STRIPE_API_KEY']);
+        });
+
+        test("Should never expose the real DD_API_KEY/DATADOG_API_KEY (the dev server's own credential) to fn", async () => {
+            const originalEnv = process.env;
+            process.env = { ...originalEnv, DD_API_KEY: 'the-dev-servers-own-api-key' };
+
+            try {
+                const seenApiKey = await runWithScopedEnv(
+                    { PATH: '/usr/bin' },
+                    async () => process.env.DD_API_KEY,
+                );
+                expect(seenApiKey).toBeUndefined();
+            } finally {
+                process.env = originalEnv;
+            }
+        });
+
+        test('Should restore the real process.env after fn resolves', async () => {
+            const realEnv = process.env;
+            await runWithScopedEnv({ PATH: '/usr/bin' }, async () => undefined);
+            expect(process.env).toBe(realEnv);
+        });
+
+        test('Should restore the real process.env even when fn throws', async () => {
+            const realEnv = process.env;
+            await expect(
+                runWithScopedEnv({ PATH: '/usr/bin' }, async () => {
+                    throw new Error('customer function boom');
+                }),
+            ).rejects.toThrow('customer function boom');
+            expect(process.env).toBe(realEnv);
+        });
+
+        // Mirrors network-guard.ts's own abandon-not-cancel protection:
+        // local-execution.ts's executions are abandoned rather than
+        // cancelled on timeout, so an abandoned runWithScopedEnv call can
+        // settle after a newer execution has started its own scoped-env
+        // window. That late settlement must not restore the real env out
+        // from under the newer, still-active window.
+        test("Should not let an abandoned runWithScopedEnv call's late restore corrupt a newer, currently-active scoped window", async () => {
+            const realEnv = process.env;
+
+            let resolveAbandoned: (() => void) | undefined;
+            const abandoned = runWithScopedEnv(
+                { PATH: '/abandoned' },
+                () =>
+                    new Promise<void>((resolve) => {
+                        resolveAbandoned = resolve;
+                    }),
+            );
+
+            // Simulates the timeout handler abandoning this execution —
+            // the real env is restored and the guard's generation moves on,
+            // exactly like local-execution.ts's timer callback.
+            forceResetEnv();
+            expect(process.env).toBe(realEnv);
+
+            // A second, newer execution starts its own scoped-env window.
+            let resolveCurrent: (() => void) | undefined;
+            const current = runWithScopedEnv(
+                { PATH: '/current' },
+                () =>
+                    new Promise<void>((resolve) => {
+                        resolveCurrent = resolve;
+                    }),
+            );
+            expect(process.env.PATH).toBe('/current');
+
+            // The abandoned execution's fn() finally settles, well after
+            // being abandoned — its own finally block must not restore the
+            // real env out from under the still-running newer window.
+            resolveAbandoned?.();
+            await abandoned;
+            expect(process.env.PATH).toBe('/current');
+
+            resolveCurrent?.();
+            await current;
+            expect(process.env).toBe(realEnv);
+        });
+
+        // Mirrors network-guard.ts's own savedX-consumed-not-just-restored
+        // invariant: without clearing savedEnv after consuming it, a later
+        // forceResetEnv() call made while the guard is idle would reinstall
+        // whatever the *previous* cycle saved, clobbering a real env change
+        // made in between.
+        test('Should not let a later, idle forceResetEnv() reinstall a stale snapshot over a real env change made since', async () => {
+            const realEnv = process.env;
+
+            await runWithScopedEnv({ PATH: '/scoped' }, async () => undefined);
+            expect(process.env).toBe(realEnv);
+
+            // A real, legitimate change to process.env after the guard's
+            // own window already closed — nothing to do with this guard.
+            process.env = { ...realEnv, SOME_NEW_VAR: 'set-after-guard-closed' };
+            const updatedRealEnv = process.env;
+
+            // Guard is idle (nothing currently scoped) — must be a true
+            // no-op, not a reinstall of the snapshot from the call above.
+            forceResetEnv();
+
+            expect(process.env).toBe(updatedRealEnv);
+            process.env = realEnv;
+        });
+    });
+
+    // Regression coverage for the /proc/.../environ backing-store bypass:
+    // swapping process.env alone doesn't stop customer code from reading the
+    // kernel-backed environ file directly on Linux to recover the dev
+    // server's real, unscoped environment.
+    describe('environ-file guard', () => {
+        test('Should block fs.readFileSync("/proc/self/environ") during an active scoped-env window', async () => {
+            await runWithScopedEnv({ PATH: '/scoped' }, async () => {
+                expect(() => fs.readFileSync('/proc/self/environ')).toThrow(
+                    /not allowed in backend functions/,
+                );
+            });
+        });
+
+        test(`Should block fs.readFileSync("/proc/${process.pid}/environ") during an active scoped-env window`, async () => {
+            await runWithScopedEnv({ PATH: '/scoped' }, async () => {
+                expect(() => fs.readFileSync(`/proc/${process.pid}/environ`)).toThrow(
+                    /not allowed in backend functions/,
+                );
+            });
+        });
+
+        test('Should block fs.promises.readFile("/proc/self/environ") during an active scoped-env window', async () => {
+            await runWithScopedEnv({ PATH: '/scoped' }, async () => {
+                await expect(fs.promises.readFile('/proc/self/environ')).rejects.toThrow(
+                    /not allowed in backend functions/,
+                );
+            });
+        });
+
+        test('Should block the callback-style fs.readFile("/proc/self/environ") during an active scoped-env window', async () => {
+            await runWithScopedEnv({ PATH: '/scoped' }, async () => {
+                expect(() => fs.readFile('/proc/self/environ', () => {})).toThrow(
+                    /not allowed in backend functions/,
+                );
+            });
+        });
+
+        test('Should not block reading /proc/self/environ once the scoped-env window has closed', async () => {
+            await runWithScopedEnv({ PATH: '/scoped' }, async () => undefined);
+
+            // Off macOS/CI, /proc doesn't exist at all — the assertion here
+            // is just that our own guard doesn't fire once idle; a real
+            // ENOENT for a nonexistent path is an unrelated, expected error.
+            expect(() => fs.readFileSync('/proc/self/environ')).not.toThrow(
+                /not allowed in backend functions/,
+            );
+        });
+
+        test('Should not block reading an unrelated real file during an active scoped-env window', async () => {
+            const tmpFile = path.join(os.tmpdir(), `env-guard-test-${process.pid}.txt`);
+            fs.writeFileSync(tmpFile, 'not a secret');
+
+            try {
+                await runWithScopedEnv({ PATH: '/scoped' }, async () => {
+                    expect(fs.readFileSync(tmpFile, 'utf8')).toBe('not a secret');
+                    await expect(fs.promises.readFile(tmpFile, 'utf8')).resolves.toBe(
+                        'not a secret',
+                    );
+                });
+            } finally {
+                fs.rmSync(tmpFile);
+            }
+        });
+    });
+});