@spences10/pi-child-env 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @spences10/pi-child-env
+
+## 0.1.0
+
+### Minor Changes
+
+- 6a85bee: Add shared child-process environment helper and prevent
+  team-mode teammates inheriting full parent env secrets.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Spence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @spences10/pi-child-env
+
+Shared safe environment builder for Pi child processes.
+
+By default it passes only a minimal non-secret baseline (`PATH`,
+locale, terminal, temp, home/user, color, and `LC_*` vars). Secrets
+and provider credentials are not inherited unless explicitly
+allowlisted.
+
+## Usage
+
+```ts
+import { create_child_process_env } from '@spences10/pi-child-env';
+
+spawn(command, args, {
+	env: create_child_process_env({
+		profile: 'team-mode',
+		explicit_env: {
+			MY_PI_TEAM_MEMBER: 'alice',
+		},
+	}),
+});
+```
+
+## Allowlists
+
+All profiles honor `MY_PI_CHILD_ENV_ALLOWLIST=NAME,OTHER_NAME`.
+
+Profile-specific allowlists:
+
+- `mcp` — `MY_PI_MCP_ENV_ALLOWLIST`
+- `lsp` — `MY_PI_LSP_ENV_ALLOWLIST`
+- `hooks` — `MY_PI_HOOKS_ENV_ALLOWLIST`
+- `team-mode` — `MY_PI_TEAM_MODE_ENV_ALLOWLIST`
+
+Use allowlists only for variables the child process truly needs.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type ChildEnvProfile = 'mcp' | 'lsp' | 'hooks' | 'team-mode';
+export interface CreateChildProcessEnvOptions {
+    profile?: ChildEnvProfile;
+    explicit_env?: Record<string, string | undefined>;
+    source_env?: NodeJS.ProcessEnv;
+    extra_allowed_keys?: readonly string[];
+    extra_allowlist_env_keys?: readonly string[];
+}
+export declare function create_child_process_env(options?: CreateChildProcessEnvOptions): NodeJS.ProcessEnv;

package/dist/index.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.create_child_process_env = create_child_process_env;
+const BASE_CHILD_ENV_KEYS = new Set([
+    'CI',
+    'COLORTERM',
+    'FORCE_COLOR',
+    'HOME',
+    'LANG',
+    'LOGNAME',
+    'NO_COLOR',
+    'PATH',
+    'SHELL',
+    'TEMP',
+    'TERM',
+    'TMP',
+    'TMPDIR',
+    'USER',
+]);
+const SHARED_ENV_ALLOWLIST_KEY = 'MY_PI_CHILD_ENV_ALLOWLIST';
+const PROFILE_ENV_ALLOWLIST_KEYS = {
+    mcp: 'MY_PI_MCP_ENV_ALLOWLIST',
+    lsp: 'MY_PI_LSP_ENV_ALLOWLIST',
+    hooks: 'MY_PI_HOOKS_ENV_ALLOWLIST',
+    'team-mode': 'MY_PI_TEAM_MODE_ENV_ALLOWLIST',
+};
+function create_child_process_env(options = {}) {
+    const source_env = options.source_env ?? process.env;
+    const env = {};
+    const allowed_keys = new Set(BASE_CHILD_ENV_KEYS);
+    for (const key of Object.keys(source_env)) {
+        if (key.startsWith('LC_'))
+            allowed_keys.add(key);
+    }
+    for (const key of options.extra_allowed_keys ?? []) {
+        if (key.trim())
+            allowed_keys.add(key.trim());
+    }
+    const allowlist_env_keys = [
+        SHARED_ENV_ALLOWLIST_KEY,
+        ...(options.profile
+            ? [PROFILE_ENV_ALLOWLIST_KEYS[options.profile]]
+            : []),
+        ...(options.extra_allowlist_env_keys ?? []),
+    ];
+    for (const allowlist_key of allowlist_env_keys) {
+        for (const key of parse_env_allowlist(source_env[allowlist_key])) {
+            allowed_keys.add(key);
+        }
+    }
+    for (const key of allowed_keys) {
+        const value = source_env[key];
+        if (typeof value === 'string')
+            env[key] = value;
+    }
+    for (const [key, value] of Object.entries(options.explicit_env ?? {})) {
+        if (typeof value === 'string')
+            env[key] = value;
+    }
+    return env;
+}
+function parse_env_allowlist(value) {
+    if (!value)
+        return [];
+    return value
+        .split(',')
+        .map((key) => key.trim())
+        .filter(Boolean);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAoCA,4DA0CC;AApED,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC;IACnC,IAAI;IACJ,WAAW;IACX,aAAa;IACb,MAAM;IACN,MAAM;IACN,SAAS;IACT,UAAU;IACV,MAAM;IACN,OAAO;IACP,MAAM;IACN,MAAM;IACN,KAAK;IACL,QAAQ;IACR,MAAM;CACN,CAAC,CAAC;AAEH,MAAM,wBAAwB,GAAG,2BAA2B,CAAC;AAE7D,MAAM,0BAA0B,GAAoC;IACnE,GAAG,EAAE,yBAAyB;IAC9B,GAAG,EAAE,yBAAyB;IAC9B,KAAK,EAAE,2BAA2B;IAClC,WAAW,EAAE,+BAA+B;CAC5C,CAAC;AAEF,SAAgB,wBAAwB,CACvC,UAAwC,EAAE;IAE1C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC;IACrD,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAElD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3C,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC;YAAE,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,kBAAkB,IAAI,EAAE,EAAE,CAAC;QACpD,IAAI,GAAG,CAAC,IAAI,EAAE;YAAE,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,kBAAkB,GAAG;QAC1B,wBAAwB;QACxB,GAAG,CAAC,OAAO,CAAC,OAAO;YAClB,CAAC,CAAC,CAAC,0BAA0B,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC/C,CAAC,CAAC,EAAE,CAAC;QACN,GAAG,CAAC,OAAO,CAAC,wBAAwB,IAAI,EAAE,CAAC;KAC3C,CAAC;IACF,KAAK,MAAM,aAAa,IAAI,kBAAkB,EAAE,CAAC;QAChD,KAAK,MAAM,GAAG,IAAI,mBAAmB,CACpC,UAAU,CAAC,aAAa,CAAC,CACzB,EAAE,CAAC;YACH,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACjD,CAAC;IAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CACxC,OAAO,CAAC,YAAY,IAAI,EAAE,CAC1B,EAAE,CAAC;QACH,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACjD,CAAC;IAED,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAyB;IACrD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,OAAO,KAAK;SACV,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;SACxB,MAAM,CAAC,OAAO,CAAC,CAAC;AACnB,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@spences10/pi-child-env",
+  "version": "0.1.0",
+  "description": "Shared safe environment builder for Pi child processes",
+  "keywords": [
+    "env",
+    "pi",
+    "pi-package",
+    "security"
+  ],
+  "license": "MIT",
+  "author": "Scott Spence <me@scottspence.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scottspence/my-pi.git",
+    "directory": "packages/pi-child-env"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.5"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import { create_child_process_env } from './index.js';
+
+describe('create_child_process_env', () => {
+	it('keeps baseline env and strips common secrets by default', () => {
+		const env = create_child_process_env({
+			source_env: {
+				PATH: '/bin',
+				HOME: '/home/test',
+				LANG: 'en_GB.UTF-8',
+				LC_ALL: 'en_GB.UTF-8',
+				ANTHROPIC_API_KEY: 'secret',
+				OPENAI_API_KEY: 'secret',
+				AWS_SECRET_ACCESS_KEY: 'secret',
+				DATABASE_URL: 'postgres://secret',
+			},
+		});
+
+		expect(env).toMatchObject({
+			PATH: '/bin',
+			HOME: '/home/test',
+			LANG: 'en_GB.UTF-8',
+			LC_ALL: 'en_GB.UTF-8',
+		});
+		expect(env.ANTHROPIC_API_KEY).toBeUndefined();
+		expect(env.OPENAI_API_KEY).toBeUndefined();
+		expect(env.AWS_SECRET_ACCESS_KEY).toBeUndefined();
+		expect(env.DATABASE_URL).toBeUndefined();
+	});
+
+	it('honors shared allowlist entries', () => {
+		const env = create_child_process_env({
+			source_env: {
+				PATH: '/bin',
+				AWS_PROFILE: 'dev',
+				MY_PI_CHILD_ENV_ALLOWLIST: ' AWS_PROFILE, , ',
+			},
+		});
+
+		expect(env.AWS_PROFILE).toBe('dev');
+	});
+
+	it('honors profile-specific allowlist entries', () => {
+		const env = create_child_process_env({
+			profile: 'team-mode',
+			source_env: {
+				PATH: '/bin',
+				ANTHROPIC_API_KEY: 'secret',
+				MY_PI_TEAM_MODE_ENV_ALLOWLIST: 'ANTHROPIC_API_KEY',
+			},
+		});
+
+		expect(env.ANTHROPIC_API_KEY).toBe('secret');
+	});
+
+	it('supports explicit env overrides and custom allowlist env keys', () => {
+		const env = create_child_process_env({
+			explicit_env: {
+				API_KEY: 'explicit',
+				EMPTY: undefined,
+			},
+			extra_allowed_keys: ['CUSTOM_HOME'],
+			extra_allowlist_env_keys: ['CUSTOM_ALLOWLIST'],
+			source_env: {
+				PATH: '/bin',
+				CUSTOM_HOME: '/custom',
+				EXTRA: 'value',
+				API_KEY: 'ambient',
+				CUSTOM_ALLOWLIST: 'EXTRA',
+			},
+		});
+
+		expect(env.API_KEY).toBe('explicit');
+		expect(env.EMPTY).toBeUndefined();
+		expect(env.CUSTOM_HOME).toBe('/custom');
+		expect(env.EXTRA).toBe('value');
+	});
+});

package/src/index.ts

@@ -0,0 +1,87 @@
+export type ChildEnvProfile = 'mcp' | 'lsp' | 'hooks' | 'team-mode';
+
+export interface CreateChildProcessEnvOptions {
+	profile?: ChildEnvProfile;
+	explicit_env?: Record<string, string | undefined>;
+	source_env?: NodeJS.ProcessEnv;
+	extra_allowed_keys?: readonly string[];
+	extra_allowlist_env_keys?: readonly string[];
+}
+
+const BASE_CHILD_ENV_KEYS = new Set([
+	'CI',
+	'COLORTERM',
+	'FORCE_COLOR',
+	'HOME',
+	'LANG',
+	'LOGNAME',
+	'NO_COLOR',
+	'PATH',
+	'SHELL',
+	'TEMP',
+	'TERM',
+	'TMP',
+	'TMPDIR',
+	'USER',
+]);
+
+const SHARED_ENV_ALLOWLIST_KEY = 'MY_PI_CHILD_ENV_ALLOWLIST';
+
+const PROFILE_ENV_ALLOWLIST_KEYS: Record<ChildEnvProfile, string> = {
+	mcp: 'MY_PI_MCP_ENV_ALLOWLIST',
+	lsp: 'MY_PI_LSP_ENV_ALLOWLIST',
+	hooks: 'MY_PI_HOOKS_ENV_ALLOWLIST',
+	'team-mode': 'MY_PI_TEAM_MODE_ENV_ALLOWLIST',
+};
+
+export function create_child_process_env(
+	options: CreateChildProcessEnvOptions = {},
+): NodeJS.ProcessEnv {
+	const source_env = options.source_env ?? process.env;
+	const env: NodeJS.ProcessEnv = {};
+	const allowed_keys = new Set(BASE_CHILD_ENV_KEYS);
+
+	for (const key of Object.keys(source_env)) {
+		if (key.startsWith('LC_')) allowed_keys.add(key);
+	}
+
+	for (const key of options.extra_allowed_keys ?? []) {
+		if (key.trim()) allowed_keys.add(key.trim());
+	}
+
+	const allowlist_env_keys = [
+		SHARED_ENV_ALLOWLIST_KEY,
+		...(options.profile
+			? [PROFILE_ENV_ALLOWLIST_KEYS[options.profile]]
+			: []),
+		...(options.extra_allowlist_env_keys ?? []),
+	];
+	for (const allowlist_key of allowlist_env_keys) {
+		for (const key of parse_env_allowlist(
+			source_env[allowlist_key],
+		)) {
+			allowed_keys.add(key);
+		}
+	}
+
+	for (const key of allowed_keys) {
+		const value = source_env[key];
+		if (typeof value === 'string') env[key] = value;
+	}
+
+	for (const [key, value] of Object.entries(
+		options.explicit_env ?? {},
+	)) {
+		if (typeof value === 'string') env[key] = value;
+	}
+
+	return env;
+}
+
+function parse_env_allowlist(value: string | undefined): string[] {
+	if (!value) return [];
+	return value
+		.split(',')
+		.map((key) => key.trim())
+		.filter(Boolean);
+}

package/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist",
+		"declaration": true,
+		"sourceMap": true
+	},
+	"include": ["src/**/*.ts"],
+	"exclude": ["src/**/*.test.ts", "node_modules", "dist"]
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "nodenext",
+		"moduleResolution": "nodenext",
+		"strict": true,
+		"esModuleInterop": true,
+		"allowSyntheticDefaultImports": true,
+		"skipLibCheck": true,
+		"types": ["node", "vitest/globals"]
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules"]
+}