@telorun/kernel 0.39.1 → 0.40.1

package/src/evaluation-context.ts

@@ -794,8 +794,7 @@ export class EvaluationContext implements IEvaluationContext {
    * trace — `variables`, masked `secrets`, resource `snapshots`, `ports`. Attached
    * to a trace's *root* span so the consumer can inspect what data the execution
    * could reference (beyond its own inputs/outputs). Only a `ModuleContext` owns a
-   * root scope; child scopes return undefined. Host `env` is deliberately omitted
-   * (it is the raw process environment — too broad/sensitive to dump).
+   * root scope; child scopes return undefined.
    */
   protected traceRootScope(): Record<string, unknown> | undefined {
     return undefined;

package/src/host-env.ts

@@ -0,0 +1,142 @@
+/**
+ * Host-environment access for the kernel, and the controller `process.env`
+ * guardrail.
+ *
+ * Controllers (and their dependencies) should not bypass a declared binding by
+ * reading its raw host env var: host configuration reaches a controller only
+ * through `ctx.env` (the snapshot the kernel threads in) or its declared
+ * `variables` / `secrets` / `ports`. To enforce that, {@link lockControllerEnv}
+ * replaces the global `process.env` with a Proxy that denies reads of exactly
+ * the env-var names the manifest binds — every other key (`NODE_ENV`, an SDK's
+ * own `AWS_*` / `SMITHY_*` config, `~/.aws` path lookups, …) passes through
+ * untouched. The kernel carries no allowlist of vendor env conventions; the
+ * denied set is derived from the manifest.
+ *
+ * This is a **guardrail, not an isolation boundary**: controllers run in the
+ * same process, so a determined one can still reach the OS environment by other
+ * means (a child process, `/proc/self/environ`, re-`defineProperty`). The Proxy
+ * stops casual / accidental bypass of a declared binding and makes it visible.
+ *
+ * The kernel itself still needs a handful of `TELO_*` / cache env vars. Those
+ * reads go through {@link hostEnv}, which returns a reference captured at module
+ * import — before any lock — so they keep working once the Proxy is installed.
+ */
+
+// The real environment, captured before any lock — and stored on `globalThis`
+// under a process-global symbol so it is shared across *every* `@telorun/kernel`
+// module instance in the process. This matters because a controller can load a
+// second copy of the kernel: the `@telorun/test` suite runner imports `Kernel`
+// to spawn child kernels in-process. That second copy's module body runs *after*
+// the main kernel already locked `process.env`, so a plain `process.env` capture
+// there would grab the (proxied) env. Reading the shared snapshot instead keeps
+// every instance's `hostEnv()` — and the subprocess env it feeds — real.
+//
+// `lockControllerEnv` only rebinds the `process.env` *property*; it never mutates
+// the original object, so this reference keeps yielding real values after a lock.
+const REAL_ENV_KEY = Symbol.for("@telorun/kernel:host-env:real-env");
+const LOCKED_KEY = Symbol.for("@telorun/kernel:host-env:locked");
+const DENIED_KEYS_KEY = Symbol.for("@telorun/kernel:host-env:denied-keys");
+const globals = globalThis as Record<symbol, unknown>;
+const REAL_ENV: NodeJS.ProcessEnv = (globals[REAL_ENV_KEY] ??=
+  process.env) as NodeJS.ProcessEnv;
+
+// Process-global set of denied env-var names — the union of every booted
+// kernel's declared `variables` / `secrets` / `ports` env keys. Shared on
+// `globalThis` so a second in-process `@telorun/kernel` copy (the test suite
+// runner spawns child kernels) and the already-installed Proxy read the same
+// live set: a kernel that boots *after* the Proxy is installed still contributes
+// its declared keys (see {@link lockControllerEnv}).
+const DENIED_KEYS: Set<string> = (globals[DENIED_KEYS_KEY] ??= new Set<string>()) as Set<string>;
+
+/** The real host environment. Kernel-internal use only — never handed to
+ *  controllers (they get the sanctioned `ctx.env` snapshot instead). */
+export function hostEnv(): NodeJS.ProcessEnv {
+  return REAL_ENV;
+}
+
+/**
+ * Build the guardrail Proxy over `backing`. A key in `deniedKeys` reads back
+ * `undefined` — even when set — and is hidden from `in` / enumeration, with the
+ * first read of each such key reported via `warn`. Every other key passes
+ * through transparently (real value, no warning, visible to `in` /
+ * enumeration). Writes pass through to `backing`.
+ *
+ * `deniedKeys` is consulted live on every trap, so keys added after the Proxy
+ * is installed take effect immediately (a later kernel's bindings).
+ *
+ * Exported for testing; production installs it via {@link lockControllerEnv}.
+ */
+export function createLockedEnv(
+  backing: NodeJS.ProcessEnv,
+  deniedKeys: ReadonlySet<string>,
+  warn: (key: string) => void,
+): NodeJS.ProcessEnv {
+  const warned = new Set<string>();
+  const denied = (key: string | symbol): boolean =>
+    typeof key === "string" && deniedKeys.has(key);
+
+  return new Proxy(backing, {
+    get(target, key) {
+      if (!denied(key)) return Reflect.get(target, key);
+      const name = key as string;
+      if (!warned.has(name)) {
+        warned.add(name);
+        warn(name);
+      }
+      return undefined;
+    },
+    has(target, key) {
+      return !denied(key) && Reflect.has(target, key);
+    },
+    ownKeys(target) {
+      return Reflect.ownKeys(target).filter((key) => !denied(key));
+    },
+    getOwnPropertyDescriptor(target, key) {
+      return denied(key) ? undefined : Reflect.getOwnPropertyDescriptor(target, key);
+    },
+    set(target, key, value) {
+      return Reflect.set(target, key, value);
+    },
+  });
+}
+
+/**
+ * Install the {@link createLockedEnv} guardrail over the global `process.env`,
+ * denying reads of `deniedKeys` — the booting kernel's declared `variables` /
+ * `secrets` / `ports` env-var names.
+ *
+ * The denied set is process-global and additive: every call unions its keys
+ * into the shared {@link DENIED_KEYS} set, even after the Proxy is installed, so
+ * each kernel that boots in the process contributes its bindings. Several
+ * `Kernel` instances can boot in one process (the test suite runs child kernels
+ * in-process), each with its own manifest; the union denies any key declared by
+ * any of them — strictly safe, since a controller has no reason to read a
+ * sibling app's declared key from the raw env.
+ *
+ * The Proxy install itself is idempotent — the flag lives on `globalThis`, so a
+ * second `@telorun/kernel` instance sees the first instance's lock and does not
+ * re-wrap. The property is left non-writable so a casual `process.env = {…}`
+ * cannot drop the guardrail (`configurable` stays true so tooling can still
+ * manage it).
+ *
+ * `warn` binds to the first kernel that boots in the process. In the common
+ * one-kernel-per-process case that is the right sink; with in-process child
+ * kernels a stray read warns to the first kernel's stderr (and dedup is
+ * process-global). Acceptable — child kernels receive an explicit env and have
+ * no reason to read a declared key from `process.env`.
+ */
+export function lockControllerEnv(
+  deniedKeys: Iterable<string>,
+  warn: (key: string) => void,
+): void {
+  for (const key of deniedKeys) DENIED_KEYS.add(key);
+  if (globals[LOCKED_KEY]) return;
+  globals[LOCKED_KEY] = true;
+
+  Object.defineProperty(process, "env", {
+    value: createLockedEnv(REAL_ENV, DENIED_KEYS, warn),
+    writable: false,
+    enumerable: true,
+    configurable: true,
+  });
+}

package/src/kernel.ts

@@ -32,6 +32,7 @@ import {
 import { parseArgs } from "util";
 import { ControllerRegistry } from "./controller-registry.js";
 import { EventBus } from "./events.js";
+import { hostEnv, lockControllerEnv } from "./host-env.js";
 import { KernelTracer } from "./tracing.js";
 import { ModuleContext } from "./module-context.js";
 import { ResourceContextImpl } from "./resource-context.js";
@@ -48,6 +49,7 @@ import {
   resolveCacheRoot,
 } from "./manifest-sources/local-manifest-cache-source.js";
 import {
+  collectDeclaredEnvKeys,
   precompileApplicationEnvSchemas,
   precompileDefinitionSchemas,
   resolveApplicationEnv,
@@ -119,6 +121,9 @@ export class Kernel implements IKernel {
    *  per name. Surfaced via {@link getResolvedPorts} so a host can advertise where
    *  the running app is reachable. */
   private _resolvedPorts: Array<{ name: string; port: number; protocol: "tcp" | "udp" }> = [];
+  // Host env-var names the root Application binds via `variables`/`secrets`/
+  // `ports`; the denied set for the `process.env` guardrail installed at boot.
+  private _declaredEnvKeys: string[] = [];
   /** The `.telo` cache root for this load, resolved once in `load()` and
    *  threaded to the validator, analysis stamp, and npm install root. */
   private _cacheRoot?: string | null;
@@ -148,7 +153,7 @@ export class Kernel implements IKernel {
     this.stdin = options.stdin ?? process.stdin;
     this.stdout = options.stdout ?? process.stdout;
     this.stderr = options.stderr ?? process.stderr;
-    this.env = options.env ?? process.env;
+    this.env = options.env ?? hostEnv();
     this.argv = options.argv ?? [];
     this.registryUrl = options.registryUrl;
     this.loader = new Loader(defaultSources(this.registryUrl), { celHandlers: nodeCelHandlers });
@@ -338,7 +343,6 @@ export class Kernel implements IKernel {
       [],
       this._createInstance.bind(this),
       (event, payload, metadata) => this.eventBus.emit(event, payload, metadata),
-      this.env,
     );
     this.rootContext.tracer = this.tracer;
     // Initialize built-in Runtime definitions first
@@ -551,6 +555,9 @@ export class Kernel implements IKernel {
     }
 
     if (rootApplicationManifest) {
+      this._declaredEnvKeys = collectDeclaredEnvKeys(
+        rootApplicationManifest as Record<string, any>,
+      );
       const { variables, secrets, ports } = resolveApplicationEnv(
         rootApplicationManifest as Record<string, any>,
         this.env,
@@ -606,6 +613,19 @@ export class Kernel implements IKernel {
     }
     this._bootCalled = true;
 
+    // Lock the ambient host environment before any controller runs: a key the
+    // manifest binds via `variables`/`secrets`/`ports` must be read through
+    // `ctx.env` or the declared binding, never the raw `process.env` var. Every
+    // other key passes through. Only real runs reach boot() — analyzeOnly loads
+    // return earlier — so analysis/editor are unaffected. The denied set is
+    // process-global and additive across in-process kernels.
+    lockControllerEnv(this._declaredEnvKeys, (key) => {
+      this.stderr.write(
+        `[telo] controller read process.env.${key} directly — ${key} is a declared ` +
+          `binding; read it through ctx.env or its variable/secret, not raw process.env.\n`,
+      );
+    });
+
     // Call register hooks for controllers actually loaded at this point (built-ins).
     // User-module kinds load their controllers during Phase 3 (Telo.Definition.init),
     // and registerController() fires their register hook there.

package/src/manifest-sources/local-manifest-cache-source.ts

@@ -5,6 +5,8 @@ import * as fs from "fs/promises";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 
+import { hostEnv } from "../host-env.js";
+
 const CACHE_SUBDIR = ".telo/manifests";
 const HTTP_NAMESPACE = "__http";
 const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
@@ -274,7 +276,7 @@ export function resolveEntryDir(entryPath: string): string | null {
  *  Consumers append the conventional subdirs: `manifests/`, `manifests/__validators/`,
  *  `npm/`. */
 export function resolveCacheRoot(entryPath: string): string | null {
-  const override = process.env.TELO_CACHE_DIR;
+  const override = hostEnv().TELO_CACHE_DIR;
   if (override && override.trim()) return path.resolve(override.trim());
   const entryDir = resolveEntryDir(entryPath);
   return entryDir ? path.join(entryDir, ".telo") : null;

package/src/module-context.ts

@@ -12,31 +12,6 @@ import type {
 import type { EmitEvent, InstanceFactory } from "@telorun/sdk";
 import { EvaluationContext } from "./evaluation-context.js";
 
-/** Wraps process.env so that missing keys return null instead of throwing in CEL.
- * cel-js uses Object.hasOwn(obj, key) before accessing obj[key], so we must
- * intercept getOwnPropertyDescriptor to report every string key as "own".
- * The `constructor` key is special-cased to return `Object` so cel-js's dyn
- * value-type matcher recognises the proxy as a plain map; Node's process.env
- * has an anonymous-function constructor that cel-js otherwise rejects with
- * "Unsupported type: object". */
-function lenientEnv(env: Record<string, string | undefined>): Record<string, string | null> {
-  return new Proxy(env as Record<string, string | null>, {
-    get(target, key) {
-      if (typeof key !== "string") return (target as any)[key];
-      if (key === "constructor") return Object as unknown as string;
-      return key in target ? (target[key] ?? null) : null;
-    },
-    has() {
-      return true;
-    },
-    getOwnPropertyDescriptor(target, key) {
-      if (typeof key !== "string") return Object.getOwnPropertyDescriptor(target, key);
-      const value = key in target ? (target[key] ?? null) : null;
-      return { configurable: true, enumerable: true, writable: true, value };
-    },
-  });
-}
-
 function collectSecretValues(secrets: Record<string, unknown>): Set<string> {
   const values = new Set<string>();
   for (const value of Object.values(secrets)) {
@@ -155,7 +130,6 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     private targets: BootTarget[] = [],
     createInstance: InstanceFactory = async () => null,
     emit: EmitEvent,
-    private readonly _hostEnv?: Record<string, string | undefined>,
   ) {
     super(source, {}, createInstance, new Set(), emit);
     this._variables = variables;
@@ -461,7 +435,6 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
       secrets: this._secrets,
       resources: this._resources,
       ports: this._ports,
-      ...(this._hostEnv ? { env: lenientEnv(this._hostEnv) } : {}),
     };
     this._secretValues = collectSecretValues(this._secrets);
   }

package/src/resource-context.ts

@@ -18,6 +18,7 @@ import {
   type TypeRule,
 } from "@telorun/sdk";
 import { isRefSentinel } from "@telorun/templating";
+import { hostEnv } from "./host-env.js";
 import { stripCompiledValues } from "./schema-compiled-values.js";
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
@@ -55,7 +56,9 @@ export class ResourceContextImpl implements ResourceContext {
     args?: ParsedArgs,
     ownerPrefix = "",
   ) {
-    this.env = env ?? process.env;
+    // `ctx.env` is the sanctioned host-env channel for controllers — always the
+    // real environment (kernel passes its snapshot), never the locked Proxy.
+    this.env = env ?? hostEnv();
     this.stdin = stdin ?? process.stdin;
     this.stdout = stdout ?? process.stdout;
     this.stderr = stderr ?? process.stderr;