envpkt 0.11.4 → 0.11.6

package/dist/cli.js

@@ -15,6 +15,37 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { createInterface } from "node:readline";
+//#region src/core/namespace.ts
+const DEFAULT_SEPARATOR = "__";
+const SHELL_SAFE_SEPARATOR_RE = /^[A-Za-z0-9_]+$/;
+/**
+* A separator is shell-safe when the resulting wire name is still a valid POSIX
+* shell identifier. Only `[A-Za-z0-9_]` qualify — `.` and `:` (and empties)
+* break `export NAME=` / `$NAME` and must be flagged.
+*/
+const isShellSafeSeparator = (separator) => SHELL_SAFE_SEPARATOR_RE.test(separator);
+/**
+* Build the logical-key → wire-name transform for a config.
+*
+* The wire name is what gets written to / read from `process.env`. It is the
+* only place a namespace prefix is applied — internal records (audit, aliases,
+* fnox lookup) stay keyed by the canonical logical name.
+*
+* A per-entry namespace overrides the file-level prefix; an explicit empty
+* string opts out (`"" ?? filePrefix` → `""`, a falsy prefix = no prefix).
+*
+* The default separator is `__` because it is the only namespace separator
+* valid in a POSIX shell identifier (`.`/`:` break shell `export`/`$VAR`).
+*/
+const makeEnvNamer = (config) => {
+	const filePrefix = config.namespace?.prefix;
+	const separator = config.namespace?.separator ?? DEFAULT_SEPARATOR;
+	return (logicalKey, entryNamespace) => {
+		const prefix = entryNamespace ?? filePrefix;
+		return prefix ? `${prefix}${separator}${logicalKey}` : logicalKey;
+	};
+};
+//#endregion
 //#region src/core/audit.ts
 const MS_PER_DAY = 864e5;
 const WARN_BEFORE_DAYS = 30;
@@ -146,13 +177,15 @@ const computeAudit = (config, fnoxKeys, today, aliasTable) => {
 };
 const computeEnvAudit = (config, env = process.env) => {
 	const envEntries = config.env ?? {};
+	const namer = makeEnvNamer(config);
+	const envWire = (key) => namer(key, envEntries[key]?.namespace);
 	const resolveEffectiveDefault = (entry) => {
 		return Do(function* () {
 			return yield* $(Option((yield* $(Option(envEntries[yield* $(Option((yield* $(Option(entry.from_key))).match(/^env\.(.+)$/)?.[1]))]))).value));
 		}).orElse(entry.value ?? "");
 	};
 	const entries = Object.entries(envEntries).map(([key, entry]) => {
-		const currentValue = env[key];
+		const currentValue = env[envWire(key)];
 		const effectiveDefault = resolveEffectiveDefault(entry);
 		return {
 			key,
@@ -197,6 +230,13 @@ const IdentitySchema = Type.Object({
 	recipient: Type.Optional(Type.String({ description: "Age public key for encryption" })),
 	secrets: Type.Optional(Type.Array(Type.String(), { description: "Secret keys needed from the catalog" }))
 }, { description: "Identity and capabilities of the principal using this envpkt" });
+const NamespaceSchema = Type.Object({
+	prefix: Type.String({ description: "Namespace prefix applied to all injected env/secret names (e.g. 'CIV' -> CIV__API_KEY)" }),
+	separator: Type.Optional(Type.String({
+		default: "__",
+		description: "Separator between prefix and key. Default '__' (shell-safe). Note: '.' and ':' are not valid in shell identifiers."
+	}))
+}, { description: "Optional namespace/package prefix for injected environment variable names" });
 const SecretMetaSchema = Type.Object({
 	service: Type.Optional(Type.String({ description: "Service or system this secret authenticates to" })),
 	expires: Type.Optional(Type.String({
@@ -225,7 +265,8 @@ const SecretMetaSchema = Type.Object({
 	encrypted_value: Type.Optional(Type.String({ description: "Age-encrypted secret value (armored ciphertext, safe to commit)" })),
 	from_key: Type.Optional(Type.String({ description: "Reference another entry (format: 'secret.<KEY>') whose resolved value this alias reuses. Mutually exclusive with encrypted_value." })),
 	required: Type.Optional(Type.Boolean({ description: "Whether this secret is required for operation" })),
-	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" }))
+	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" })),
+	namespace: Type.Optional(Type.String({ description: "Override the file-level namespace for this entry's injected name. Empty string opts out of any prefix." }))
 }, { description: "Metadata about a single secret" });
 const LifecycleConfigSchema = Type.Object({
 	stale_warning_days: Type.Optional(Type.Number({
@@ -252,7 +293,8 @@ const EnvMetaSchema = Type.Object({
 	from_key: Type.Optional(Type.String({ description: "Reference another entry (format: 'env.<KEY>') whose resolved value this alias reuses. Mutually exclusive with value." })),
 	purpose: Type.Optional(Type.String({ description: "Why this env var exists" })),
 	comment: Type.Optional(Type.String({ description: "Free-form annotation or note" })),
-	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" }))
+	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" })),
+	namespace: Type.Optional(Type.String({ description: "Override the file-level namespace for this entry's injected name. Empty string opts out of any prefix." }))
 }, { description: "Metadata for a plaintext environment default (non-secret)" });
 const EnvpktConfigSchema = Type.Object({
 	version: Type.Number({
@@ -260,6 +302,7 @@ const EnvpktConfigSchema = Type.Object({
 		default: 1
 	}),
 	catalog: Type.Optional(Type.String({ description: "Path to shared secret catalog (relative to this config file)" })),
+	namespace: Type.Optional(NamespaceSchema),
 	identity: Type.Optional(IdentitySchema),
 	secret: Type.Optional(Type.Record(Type.String(), SecretMetaSchema, { description: "Per-secret metadata keyed by secret name" })),
 	env: Type.Optional(Type.Record(Type.String(), EnvMetaSchema, { description: "Plaintext environment defaults keyed by variable name" })),
@@ -1303,6 +1346,13 @@ const bootSafe = (options) => {
 		log.debug("alias.validate.success", { aliases: aliasTable.entries.size });
 		const secretEntries = config.secret ?? {};
 		const envEntries = config.env ?? {};
+		const namer = makeEnvNamer(config);
+		const secretEnv = (key) => namer(key, secretEntries[key]?.namespace);
+		const envEnv = (key) => namer(key, envEntries[key]?.namespace);
+		const envNames = {
+			...Object.fromEntries(Object.keys(envEntries).map((k) => [k, envEnv(k)])),
+			...Object.fromEntries(Object.keys(secretEntries).map((k) => [k, secretEnv(k)]))
+		};
 		const nonAliasSecretEntries = Object.fromEntries(Object.entries(secretEntries).filter(([, meta]) => meta.from_key === void 0));
 		const aliasSecretKeys = Object.entries(secretEntries).filter(([, meta]) => meta.from_key !== void 0).map(([k]) => k);
 		const nonAliasEnvEntries = Object.entries(envEntries).filter(([, meta]) => meta.from_key === void 0);
@@ -1321,10 +1371,12 @@ const bootSafe = (options) => {
 			const injected = [];
 			const skipped = [];
 			warnings.push(...checkEnvMisclassification(config));
-			const envDefaults = Object.fromEntries(nonAliasEnvEntries.flatMap(([key, entry]) => Option(process.env[key]).fold(() => Option(entry.value).fold(() => [], (v) => [[key, v]]), () => [])));
-			const overridden = nonAliasEnvEntries.flatMap(([key]) => Option(process.env[key]).fold(() => [], () => [key]));
+			const nsSeparator = config.namespace?.separator;
+			if (nsSeparator !== void 0 && !isShellSafeSeparator(nsSeparator)) warnings.push(`[namespace] separator "${nsSeparator}" is not shell-safe — injected names won't be usable via shell $VAR/export. Use '_' or '__'.`);
+			const envDefaults = Object.fromEntries(nonAliasEnvEntries.flatMap(([key, entry]) => Option(process.env[envEnv(key)]).fold(() => Option(entry.value).fold(() => [], (v) => [[key, v]]), () => [])));
+			const overridden = nonAliasEnvEntries.flatMap(([key]) => Option(process.env[envEnv(key)]).fold(() => [], () => [key]));
 			if (inject) Object.entries(envDefaults).forEach(([key, value]) => {
-				process.env[key] = value;
+				process.env[envEnv(key)] = value;
 			});
 			const sealedKeys = /* @__PURE__ */ new Set();
 			const identityFilePath = resolveIdentityFilePath(config, configDir, true);
@@ -1399,20 +1451,20 @@ const bootSafe = (options) => {
 			aliasEnvKeys.forEach((aliasKey) => {
 				const entry = aliasTable.entries.get(`env.${aliasKey}`);
 				if (!entry) return;
-				if (process.env[aliasKey] !== void 0) {
+				if (process.env[envEnv(aliasKey)] !== void 0) {
 					overridden.push(aliasKey);
 					return;
 				}
 				const targetEntry = envEntries[entry.targetKey];
 				if (targetEntry?.value === void 0) return;
-				envDefaults[aliasKey] = process.env[entry.targetKey] ?? targetEntry.value;
+				envDefaults[aliasKey] = process.env[envEnv(entry.targetKey)] ?? targetEntry.value;
 			});
 			if (inject) {
 				Object.entries(envDefaults).forEach(([key, value]) => {
-					process.env[key] ??= value;
+					process.env[envEnv(key)] ??= value;
 				});
 				Object.entries(secrets).forEach(([key, value]) => {
-					process.env[key] = value;
+					process.env[secretEnv(key)] = value;
 				});
 			}
 			return {
@@ -1423,6 +1475,7 @@ const bootSafe = (options) => {
 				warnings,
 				envDefaults,
 				overridden,
+				envNames,
 				configPath,
 				configSource
 			};
@@ -2153,11 +2206,16 @@ const envCheck = (config, env) => {
 	const secretEntries = config.secret ?? {};
 	const metaKeys = Object.keys(secretEntries);
 	const metaKeysSet = Set$1(metaKeys);
+	const namer = makeEnvNamer(config);
+	const envDefaultsForWire = config.env ?? {};
+	const secretWire = (key) => namer(key, secretEntries[key]?.namespace);
+	const envWire = (key) => namer(key, envDefaultsForWire[key]?.namespace);
+	const isPresentAt = (wire) => env[wire] !== void 0 && env[wire] !== "";
 	const isSecretPresent = (key) => {
-		if (env[key] !== void 0 && env[key] !== "") return true;
+		if (isPresentAt(secretWire(key))) return true;
 		const meta = secretEntries[key];
 		if (meta?.from_key === void 0) return false;
-		return parseAliasRef(meta.from_key, "secret").fold(() => false, (targetKey) => env[targetKey] !== void 0 && env[targetKey] !== "");
+		return parseAliasRef(meta.from_key, "secret").fold(() => false, (targetKey) => isPresentAt(secretWire(targetKey)));
 	};
 	const secretDriftEntries = Object.entries(secretEntries).map(([key, meta]) => {
 		const present = isSecretPresent(key);
@@ -2170,10 +2228,10 @@ const envCheck = (config, env) => {
 	});
 	const envDefaults = config.env ?? {};
 	const isEnvPresent = (key) => {
-		if (env[key] !== void 0 && env[key] !== "") return true;
+		if (isPresentAt(envWire(key))) return true;
 		const meta = envDefaults[key];
 		if (meta?.from_key === void 0) return false;
-		return parseAliasRef(meta.from_key, "env").fold(() => false, (targetKey) => env[targetKey] !== void 0 && env[targetKey] !== "");
+		return parseAliasRef(meta.from_key, "env").fold(() => false, (targetKey) => isPresentAt(envWire(targetKey)));
 	};
 	const envDefaultEntries = Object.keys(envDefaults).filter((key) => !metaKeysSet.has(key)).map((key) => {
 		const present = isEnvPresent(key);
@@ -2184,7 +2242,7 @@ const envCheck = (config, env) => {
 			confidence: Option(void 0)
 		};
 	});
-	const trackedKeys = Set$1([...metaKeys, ...envDefaultEntries.map((e) => e.envVar)]);
+	const trackedKeys = Set$1([...metaKeys.map(secretWire), ...envDefaultEntries.map((e) => envWire(e.envVar))]);
 	const untrackedEntries = scanEnv(env).filter((match) => !trackedKeys.has(match.envVar)).map((match) => ({
 		envVar: match.envVar,
 		service: match.service,
@@ -2650,19 +2708,22 @@ const runEnvExport = (options) => {
 		boot.warnings.forEach((warning) => {
 			console.error(`${YELLOW}Warning:${RESET} ${warning}`);
 		});
+		const wireName = (key) => boot.envNames[key] ?? key;
 		Object.entries(boot.envDefaults).forEach(([key, value]) => {
-			console.log(`export ${key}='${shellEscape(value)}'`);
+			console.log(`export ${wireName(key)}='${shellEscape(value)}'`);
 		});
 		if (boot.overridden.length > 0) loadConfig(boot.configPath).fold(() => {}, (config) => {
 			const envEntries = config.env ?? {};
 			boot.overridden.forEach((key) => {
 				if (!(key in envEntries)) return;
-				const value = envEntries[key].value ?? process.env[key] ?? "";
-				console.log(`export ${key}='${shellEscape(value)}'`);
+				const entry = envEntries[key];
+				const name = wireName(key);
+				const value = entry.value ?? process.env[name] ?? "";
+				console.log(`export ${name}='${shellEscape(value)}'`);
 			});
 		});
 		Object.entries(boot.secrets).forEach(([key, value]) => {
-			console.log(`export ${key}='${shellEscape(value)}'`);
+			console.log(`export ${wireName(key)}='${shellEscape(value)}'`);
 		});
 	});
 };
@@ -2919,11 +2980,13 @@ const runExec = (args, options) => {
 		console.error(`${YELLOW}Warning:${RESET} ${warning}`);
 	});
 	const env = { ...process.env };
+	const wireName = (key) => boot.envNames[key] ?? key;
 	Object.entries(boot.envDefaults).forEach(([key, value]) => {
-		if (!(key in env)) env[key] = value;
+		const name = wireName(key);
+		if (!(name in env)) env[name] = value;
 	});
 	Object.entries(boot.secrets).forEach(([key, value]) => {
-		env[key] = value;
+		env[wireName(key)] = value;
 	});
 	const [cmd, ...cmdArgs] = args;
 	Try(() => execFileSync(cmd, cmdArgs, {
@@ -3850,6 +3913,12 @@ const runSeal = async (options) => {
 			console.error(`${DIM}Available keys: ${Object.keys(allSecretEntries).join(", ")}${RESET}`);
 			process.exit(2);
 		}
+		const aliasKeys = editKeys.filter((k) => allSecretEntries[k].from_key !== void 0);
+		if (aliasKeys.length > 0) {
+			console.error(`${RED}Error:${RESET} Cannot seal alias entries: ${aliasKeys.join(", ")}`);
+			console.error(`${DIM}Aliases reference another secret's value via from_key — seal the target instead.${RESET}`);
+			process.exit(2);
+		}
 		if (!process.stdin.isTTY) {
 			console.error(`${RED}Error:${RESET} --edit requires an interactive terminal`);
 			process.exit(2);
@@ -3888,9 +3957,14 @@ const runSeal = async (options) => {
 		return;
 	}
 	const allSecretEntries = config.secret ?? {};
-	const allKeys = Object.keys(allSecretEntries);
+	const allKeys = Object.keys(allSecretEntries).filter((k) => allSecretEntries[k].from_key === void 0);
+	const skippedAliases = Object.keys(allSecretEntries).filter((k) => allSecretEntries[k].from_key !== void 0);
 	const alreadySealed = allKeys.filter((k) => allSecretEntries[k].encrypted_value);
 	const unsealed = allKeys.filter((k) => !allSecretEntries[k].encrypted_value);
+	if (skippedAliases.length > 0) {
+		const noun = skippedAliases.length === 1 ? "alias" : "aliases";
+		console.error(`${DIM}Skipping ${skippedAliases.length} ${noun}: ${skippedAliases.join(", ")}${RESET}`);
+	}
 	if (!options.reseal && alreadySealed.length > 0) {
 		if (unsealed.length === 0) {
 			console.log(`${GREEN}✓${RESET} All ${BOLD}${alreadySealed.length}${RESET} secret(s) already sealed. Use ${CYAN}--reseal${RESET} to re-encrypt.`);

package/dist/index.d.ts

@@ -49,6 +49,7 @@ declare const SecretMetaSchema: import("@sinclair/typebox").TObject<{
   from_key: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
   required: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
   tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+  namespace: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
 type SecretMeta = Static<typeof SecretMetaSchema>;
 declare const LifecycleConfigSchema: import("@sinclair/typebox").TObject<{
@@ -71,11 +72,16 @@ declare const EnvMetaSchema: import("@sinclair/typebox").TObject<{
   purpose: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
   comment: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
   tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+  namespace: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
 type EnvMeta = Static<typeof EnvMetaSchema>;
 declare const EnvpktConfigSchema: import("@sinclair/typebox").TObject<{
   version: import("@sinclair/typebox").TNumber;
   catalog: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+  namespace: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+    prefix: import("@sinclair/typebox").TString;
+    separator: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+  }>>;
   identity: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
     name: import("@sinclair/typebox").TString;
     consumer: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"agent">, import("@sinclair/typebox").TLiteral<"service">, import("@sinclair/typebox").TLiteral<"developer">, import("@sinclair/typebox").TLiteral<"ci">]>>;
@@ -104,6 +110,7 @@ declare const EnvpktConfigSchema: import("@sinclair/typebox").TObject<{
     from_key: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     required: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+    namespace: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
   }>>>;
   env: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
     value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -111,6 +118,7 @@ declare const EnvpktConfigSchema: import("@sinclair/typebox").TObject<{
     purpose: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     comment: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+    namespace: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
   }>>>;
   lifecycle: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
     stale_warning_days: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
@@ -305,6 +313,13 @@ type BootResult = {
   readonly warnings: ReadonlyArray<string>;
   readonly envDefaults: Readonly<Record<string, string>>;
   readonly overridden: ReadonlyArray<string>;
+  /**
+   * Map of logical key → injected wire name (e.g. API_KEY → CIV__API_KEY).
+   * `secrets`/`envDefaults` stay keyed by the logical name; this is how
+   * shell-facing consumers (exec, env export) recover the actual process.env
+   * name. Identity map when no namespace is configured.
+   */
+  readonly envNames: Readonly<Record<string, string>>;
   readonly configPath: string;
   readonly configSource: ConfigSource;
 };

package/dist/index.js

@@ -39,6 +39,13 @@ const IdentitySchema = Type.Object({
 }, { description: "Identity and capabilities of the principal using this envpkt" });
 /** @deprecated Use `IdentitySchema` instead */
 const AgentIdentitySchema = IdentitySchema;
+const NamespaceSchema = Type.Object({
+	prefix: Type.String({ description: "Namespace prefix applied to all injected env/secret names (e.g. 'CIV' -> CIV__API_KEY)" }),
+	separator: Type.Optional(Type.String({
+		default: "__",
+		description: "Separator between prefix and key. Default '__' (shell-safe). Note: '.' and ':' are not valid in shell identifiers."
+	}))
+}, { description: "Optional namespace/package prefix for injected environment variable names" });
 const SecretMetaSchema = Type.Object({
 	service: Type.Optional(Type.String({ description: "Service or system this secret authenticates to" })),
 	expires: Type.Optional(Type.String({
@@ -67,7 +74,8 @@ const SecretMetaSchema = Type.Object({
 	encrypted_value: Type.Optional(Type.String({ description: "Age-encrypted secret value (armored ciphertext, safe to commit)" })),
 	from_key: Type.Optional(Type.String({ description: "Reference another entry (format: 'secret.<KEY>') whose resolved value this alias reuses. Mutually exclusive with encrypted_value." })),
 	required: Type.Optional(Type.Boolean({ description: "Whether this secret is required for operation" })),
-	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" }))
+	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" })),
+	namespace: Type.Optional(Type.String({ description: "Override the file-level namespace for this entry's injected name. Empty string opts out of any prefix." }))
 }, { description: "Metadata about a single secret" });
 const LifecycleConfigSchema = Type.Object({
 	stale_warning_days: Type.Optional(Type.Number({
@@ -94,7 +102,8 @@ const EnvMetaSchema = Type.Object({
 	from_key: Type.Optional(Type.String({ description: "Reference another entry (format: 'env.<KEY>') whose resolved value this alias reuses. Mutually exclusive with value." })),
 	purpose: Type.Optional(Type.String({ description: "Why this env var exists" })),
 	comment: Type.Optional(Type.String({ description: "Free-form annotation or note" })),
-	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" }))
+	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" })),
+	namespace: Type.Optional(Type.String({ description: "Override the file-level namespace for this entry's injected name. Empty string opts out of any prefix." }))
 }, { description: "Metadata for a plaintext environment default (non-secret)" });
 const EnvpktConfigSchema = Type.Object({
 	version: Type.Number({
@@ -102,6 +111,7 @@ const EnvpktConfigSchema = Type.Object({
 		default: 1
 	}),
 	catalog: Type.Optional(Type.String({ description: "Path to shared secret catalog (relative to this config file)" })),
+	namespace: Type.Optional(NamespaceSchema),
 	identity: Type.Optional(IdentitySchema),
 	secret: Type.Optional(Type.Record(Type.String(), SecretMetaSchema, { description: "Per-secret metadata keyed by secret name" })),
 	env: Type.Optional(Type.Record(Type.String(), EnvMetaSchema, { description: "Plaintext environment defaults keyed by variable name" })),
@@ -557,6 +567,37 @@ const formatPacket = (result, options) => {
 	return sections.join("\n\n");
 };
 //#endregion
+//#region src/core/namespace.ts
+const DEFAULT_SEPARATOR = "__";
+const SHELL_SAFE_SEPARATOR_RE = /^[A-Za-z0-9_]+$/;
+/**
+* A separator is shell-safe when the resulting wire name is still a valid POSIX
+* shell identifier. Only `[A-Za-z0-9_]` qualify — `.` and `:` (and empties)
+* break `export NAME=` / `$NAME` and must be flagged.
+*/
+const isShellSafeSeparator = (separator) => SHELL_SAFE_SEPARATOR_RE.test(separator);
+/**
+* Build the logical-key → wire-name transform for a config.
+*
+* The wire name is what gets written to / read from `process.env`. It is the
+* only place a namespace prefix is applied — internal records (audit, aliases,
+* fnox lookup) stay keyed by the canonical logical name.
+*
+* A per-entry namespace overrides the file-level prefix; an explicit empty
+* string opts out (`"" ?? filePrefix` → `""`, a falsy prefix = no prefix).
+*
+* The default separator is `__` because it is the only namespace separator
+* valid in a POSIX shell identifier (`.`/`:` break shell `export`/`$VAR`).
+*/
+const makeEnvNamer = (config) => {
+	const filePrefix = config.namespace?.prefix;
+	const separator = config.namespace?.separator ?? DEFAULT_SEPARATOR;
+	return (logicalKey, entryNamespace) => {
+		const prefix = entryNamespace ?? filePrefix;
+		return prefix ? `${prefix}${separator}${logicalKey}` : logicalKey;
+	};
+};
+//#endregion
 //#region src/core/audit.ts
 const MS_PER_DAY = 864e5;
 const WARN_BEFORE_DAYS = 30;
@@ -688,13 +729,15 @@ const computeAudit = (config, fnoxKeys, today, aliasTable) => {
 };
 const computeEnvAudit = (config, env = process.env) => {
 	const envEntries = config.env ?? {};
+	const namer = makeEnvNamer(config);
+	const envWire = (key) => namer(key, envEntries[key]?.namespace);
 	const resolveEffectiveDefault = (entry) => {
 		return Do(function* () {
 			return yield* $(Option((yield* $(Option(envEntries[yield* $(Option((yield* $(Option(entry.from_key))).match(/^env\.(.+)$/)?.[1]))]))).value));
 		}).orElse(entry.value ?? "");
 	};
 	const entries = Object.entries(envEntries).map(([key, entry]) => {
-		const currentValue = env[key];
+		const currentValue = env[envWire(key)];
 		const effectiveDefault = resolveEffectiveDefault(entry);
 		return {
 			key,
@@ -1437,11 +1480,16 @@ const envCheck = (config, env) => {
 	const secretEntries = config.secret ?? {};
 	const metaKeys = Object.keys(secretEntries);
 	const metaKeysSet = Set$1(metaKeys);
+	const namer = makeEnvNamer(config);
+	const envDefaultsForWire = config.env ?? {};
+	const secretWire = (key) => namer(key, secretEntries[key]?.namespace);
+	const envWire = (key) => namer(key, envDefaultsForWire[key]?.namespace);
+	const isPresentAt = (wire) => env[wire] !== void 0 && env[wire] !== "";
 	const isSecretPresent = (key) => {
-		if (env[key] !== void 0 && env[key] !== "") return true;
+		if (isPresentAt(secretWire(key))) return true;
 		const meta = secretEntries[key];
 		if (meta?.from_key === void 0) return false;
-		return parseAliasRef(meta.from_key, "secret").fold(() => false, (targetKey) => env[targetKey] !== void 0 && env[targetKey] !== "");
+		return parseAliasRef(meta.from_key, "secret").fold(() => false, (targetKey) => isPresentAt(secretWire(targetKey)));
 	};
 	const secretDriftEntries = Object.entries(secretEntries).map(([key, meta]) => {
 		const present = isSecretPresent(key);
@@ -1454,10 +1502,10 @@ const envCheck = (config, env) => {
 	});
 	const envDefaults = config.env ?? {};
 	const isEnvPresent = (key) => {
-		if (env[key] !== void 0 && env[key] !== "") return true;
+		if (isPresentAt(envWire(key))) return true;
 		const meta = envDefaults[key];
 		if (meta?.from_key === void 0) return false;
-		return parseAliasRef(meta.from_key, "env").fold(() => false, (targetKey) => env[targetKey] !== void 0 && env[targetKey] !== "");
+		return parseAliasRef(meta.from_key, "env").fold(() => false, (targetKey) => isPresentAt(envWire(targetKey)));
 	};
 	const envDefaultEntries = Object.keys(envDefaults).filter((key) => !metaKeysSet.has(key)).map((key) => {
 		const present = isEnvPresent(key);
@@ -1468,7 +1516,7 @@ const envCheck = (config, env) => {
 			confidence: Option(void 0)
 		};
 	});
-	const trackedKeys = Set$1([...metaKeys, ...envDefaultEntries.map((e) => e.envVar)]);
+	const trackedKeys = Set$1([...metaKeys.map(secretWire), ...envDefaultEntries.map((e) => envWire(e.envVar))]);
 	const untrackedEntries = scanEnv(env).filter((match) => !trackedKeys.has(match.envVar)).map((match) => ({
 		envVar: match.envVar,
 		service: match.service,
@@ -1927,6 +1975,13 @@ const bootSafe = (options) => {
 		log.debug("alias.validate.success", { aliases: aliasTable.entries.size });
 		const secretEntries = config.secret ?? {};
 		const envEntries = config.env ?? {};
+		const namer = makeEnvNamer(config);
+		const secretEnv = (key) => namer(key, secretEntries[key]?.namespace);
+		const envEnv = (key) => namer(key, envEntries[key]?.namespace);
+		const envNames = {
+			...Object.fromEntries(Object.keys(envEntries).map((k) => [k, envEnv(k)])),
+			...Object.fromEntries(Object.keys(secretEntries).map((k) => [k, secretEnv(k)]))
+		};
 		const nonAliasSecretEntries = Object.fromEntries(Object.entries(secretEntries).filter(([, meta]) => meta.from_key === void 0));
 		const aliasSecretKeys = Object.entries(secretEntries).filter(([, meta]) => meta.from_key !== void 0).map(([k]) => k);
 		const nonAliasEnvEntries = Object.entries(envEntries).filter(([, meta]) => meta.from_key === void 0);
@@ -1945,10 +2000,12 @@ const bootSafe = (options) => {
 			const injected = [];
 			const skipped = [];
 			warnings.push(...checkEnvMisclassification(config));
-			const envDefaults = Object.fromEntries(nonAliasEnvEntries.flatMap(([key, entry]) => Option(process.env[key]).fold(() => Option(entry.value).fold(() => [], (v) => [[key, v]]), () => [])));
-			const overridden = nonAliasEnvEntries.flatMap(([key]) => Option(process.env[key]).fold(() => [], () => [key]));
+			const nsSeparator = config.namespace?.separator;
+			if (nsSeparator !== void 0 && !isShellSafeSeparator(nsSeparator)) warnings.push(`[namespace] separator "${nsSeparator}" is not shell-safe — injected names won't be usable via shell $VAR/export. Use '_' or '__'.`);
+			const envDefaults = Object.fromEntries(nonAliasEnvEntries.flatMap(([key, entry]) => Option(process.env[envEnv(key)]).fold(() => Option(entry.value).fold(() => [], (v) => [[key, v]]), () => [])));
+			const overridden = nonAliasEnvEntries.flatMap(([key]) => Option(process.env[envEnv(key)]).fold(() => [], () => [key]));
 			if (inject) Object.entries(envDefaults).forEach(([key, value]) => {
-				process.env[key] = value;
+				process.env[envEnv(key)] = value;
 			});
 			const sealedKeys = /* @__PURE__ */ new Set();
 			const identityFilePath = resolveIdentityFilePath(config, configDir, true);
@@ -2023,20 +2080,20 @@ const bootSafe = (options) => {
 			aliasEnvKeys.forEach((aliasKey) => {
 				const entry = aliasTable.entries.get(`env.${aliasKey}`);
 				if (!entry) return;
-				if (process.env[aliasKey] !== void 0) {
+				if (process.env[envEnv(aliasKey)] !== void 0) {
 					overridden.push(aliasKey);
 					return;
 				}
 				const targetEntry = envEntries[entry.targetKey];
 				if (targetEntry?.value === void 0) return;
-				envDefaults[aliasKey] = process.env[entry.targetKey] ?? targetEntry.value;
+				envDefaults[aliasKey] = process.env[envEnv(entry.targetKey)] ?? targetEntry.value;
 			});
 			if (inject) {
 				Object.entries(envDefaults).forEach(([key, value]) => {
-					process.env[key] ??= value;
+					process.env[envEnv(key)] ??= value;
 				});
 				Object.entries(secrets).forEach(([key, value]) => {
-					process.env[key] = value;
+					process.env[secretEnv(key)] = value;
 				});
 			}
 			return {
@@ -2047,6 +2104,7 @@ const bootSafe = (options) => {
 				warnings,
 				envDefaults,
 				overridden,
+				envNames,
 				configPath,
 				configSource
 			};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envpkt",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "description": "Credential lifecycle and fleet management for AI agents",
   "keywords": [
     "credentials",
@@ -41,17 +41,17 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@sinclair/typebox": "^0.34.49",
-    "commander": "^14.0.3",
-    "functype": "^0.60.7",
-    "functype-log": "^0.60.7",
-    "functype-os": "^0.60.7",
+    "commander": "^15.0.0",
+    "functype": "^1.3.0",
+    "functype-log": "^1.3.0",
+    "functype-os": "^1.3.0",
     "smol-toml": "^1.6.1"
   },
   "devDependencies": {
-    "@types/node": "^24.12.4",
-    "ts-builds": "^2.8.1",
-    "tsdown": "^0.22.0",
-    "tsx": "^4.22.3"
+    "@types/node": "^24.13.1",
+    "ts-builds": "^3.0.0",
+    "tsdown": "^0.22.2",
+    "tsx": "^4.22.4"
   },
   "type": "module",
   "main": "./dist/index.js",
@@ -71,5 +71,5 @@
     "schemas"
   ],
   "prettier": "ts-builds/prettier",
-  "packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319"
+  "packageManager": "pnpm@11.5.2+sha512.71c631e382066efc25625d5cf029075de07b61b37f6e27350fbd84b1bda5864c8c1967adc280776b45c30a715c0359a3be08fef42d5bb09e2b99029979692916"
 }

package/schemas/envpkt.schema.json

@@ -17,6 +17,24 @@
       "description": "Path to shared secret catalog (relative to this config file)",
       "type": "string"
     },
+    "namespace": {
+      "description": "Optional namespace/package prefix for injected environment variable names",
+      "type": "object",
+      "required": [
+        "prefix"
+      ],
+      "properties": {
+        "prefix": {
+          "description": "Namespace prefix applied to all injected env/secret names (e.g. 'CIV' -> CIV__API_KEY)",
+          "type": "string"
+        },
+        "separator": {
+          "default": "__",
+          "description": "Separator between prefix and key. Default '__' (shell-safe). Note: '.' and ':' are not valid in shell identifiers.",
+          "type": "string"
+        }
+      }
+    },
     "identity": {
       "description": "Identity and capabilities of the principal using this envpkt",
       "type": "object",
@@ -172,6 +190,10 @@
                   "type": "string"
                 }
               }
+            },
+            "namespace": {
+              "description": "Override the file-level namespace for this entry's injected name. Empty string opts out of any prefix.",
+              "type": "string"
             }
           }
         }
@@ -209,6 +231,10 @@
                   "type": "string"
                 }
               }
+            },
+            "namespace": {
+              "description": "Override the file-level namespace for this entry's injected name. Empty string opts out of any prefix.",
+              "type": "string"
             }
           }
         }