Implement conditional dotenv feature

Author: canvrno-oai

codex-rs/Cargo.lock

@@ -23,8 +23,11 @@ codex-shell-escalation = { workspace = true }
 codex-utils-absolute-path = { workspace = true }
 codex-utils-home-dir = { workspace = true }
 dotenvy = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
 tempfile = { workspace = true }
 tokio = { workspace = true, features = ["rt-multi-thread"] }
+url = { workspace = true }
 
 [target.'cfg(windows)'.dependencies]
 codex-windows-sandbox = { workspace = true }

codex-rs/arg0/Cargo.toml

@@ -0,0 +1,253 @@
+# Conditional dotenv overlays
+
+## Status
+
+This document describes the initial implementation of conditional dotenv overlays in the Codex
+startup path.
+
+## Goal
+
+Allow a packaged Codex binary to select additional environment variables at process startup based
+on local conditions. The selected variables must be visible before Codex creates its main thread,
+Tokio runtime, network clients, workers, or sessions.
+
+The motivating use case is enabling proxy variables only when an enterprise proxy is reachable,
+but the mechanism is intentionally not proxy-specific.
+
+## File model
+
+Codex continues to load `${CODEX_HOME}/.env` unconditionally. It then discovers regular files in
+`CODEX_HOME` whose names begin with `.env.`. Conditional files are processed in lexicographic
+filename order.
+
+Every conditional file must begin with a condition directive as its first non-empty line:
+
+```dotenv
+# codex-env-if: {"type":"tcp_connect","from":"HTTPS_PROXY","timeout_ms":500}
+
+HTTPS_PROXY=http://proxy.example.com:8080
+HTTP_PROXY=http://proxy.example.com:8080
+ALL_PROXY=http://proxy.example.com:8080
+NO_PROXY=localhost,127.0.0.1,.example.com
+TEST_VAR=APPLES
+```
+
+The directive is a dotenv comment, so the remainder of the file stays compatible with ordinary
+dotenv tooling. Codex parses the JSON payload before passing the file through `dotenvy`.
+
+Files without the directive are ignored. This prevents unrelated files such as `.env.example` or
+backups from being applied accidentally.
+
+## Conditions
+
+The initial implementation supports these leaf evaluators:
+
+- `tcp_connect`: attempt a TCP connection. The endpoint can come from a variable declared in the
+  same overlay via `from`, or from explicit `host` and `port` fields. Proxy URLs with credentials
+  are parsed without logging their values.
+- `file_exists`: test a file path. Relative paths are resolved against `CODEX_HOME`.
+- `env_equals`: compare an already-applied process environment variable with a string.
+- `os`: compare against Rust's operating-system identifier, such as `macos`, `linux`, or `windows`.
+
+Conditions can be composed with `not`, `all`, and `any`:
+
+```dotenv
+# codex-env-if: {"all":[{"type":"os","value":"macos"},{"not":{"type":"env_equals","name":"DISABLE_CORPORATE_ENV","value":"1"}}]}
+```
+
+Condition nesting and list sizes are bounded. Invalid conditions fail closed: Codex skips the
+overlay and reports a warning without printing environment values.
+
+The `tcp_connect` timeout is bounded. Hostname resolution uses the operating system's synchronous
+resolver and can take longer than the connection timeout; using an IP address avoids that
+uncertainty when a strictly bounded probe is required.
+
+## Applying and unsetting values
+
+When a condition passes, Codex first applies an optional unset directive and then applies the
+dotenv assignments:
+
+```dotenv
+# codex-env-if: {"not":{"type":"tcp_connect","host":"proxy.example.com","port":8080,"timeout_ms":500}}
+# codex-env-unset: ["HTTPS_PROXY","HTTP_PROXY","ALL_PROXY","NO_PROXY"]
+
+TEST_VAR=APPLES
+```
+
+Later passing overlays override values from `.env` and earlier overlays. A failing overlay makes no
+changes.
+
+As with the existing `.env` loader, conditional overlays cannot set or unset variables whose names
+begin with `CODEX_`, compared case-insensitively. The mechanism otherwise supports arbitrary
+environment-variable names and is not limited to proxy settings.
+
+## Startup lifecycle
+
+Conditional overlays are loaded from `codex_arg0::arg0_dispatch`, at the same single-threaded point
+where `.env` is currently loaded:
+
+1. Load `.env`.
+2. Discover, parse, evaluate, and apply matching `.env.*` overlays.
+3. Prepare the packaged helper `PATH` entries.
+4. Spawn the `codex-main` thread.
+5. Construct Tokio and initialize the selected Codex entry point.
+
+Evaluators are synchronous and do not create threads or a runtime. The TCP probe is the only
+network operation supported by the initial evaluators, and it does not depend on proxy environment
+variables.
+
+Conditions are evaluated once per process. Users restart Codex after moving between networks.
+
+## Security and managed delivery
+
+Discovery is limited to `CODEX_HOME`; project-local `.env.*` files are never considered. The
+initial evaluator set is declarative and cannot execute commands.
+
+An arbitrary command evaluator is deliberately deferred. Automatically running user-controlled or
+cloud-delivered code before the Codex security and approval systems initialize requires explicit
+trust semantics, bounded execution, and—for managed delivery—a server-authenticated signature over
+the evaluator and its metadata.
+
+Cloud or MDM delivery can write the dotenv overlays as data. If delivery happens after the current
+Codex process has started, Codex must be restarted before the new overlay can affect that process.
+
+## Validation
+
+The minimum end-to-end validation is:
+
+1. Put `TEST_VAR=APPLES` in a passing conditional overlay.
+2. Start the packaged Codex binary normally.
+3. From a local Codex thread, run a command that prints `TEST_VAR` and verify that it is `APPLES`.
+4. Repeat with the condition failing and verify that the overlay is absent.
+5. Test proxy and direct networks with a full Codex restart between them, confirming that proxy
+   variables are present only when intended.
+
+## Enterprise deployment
+
+The local TUI and the packaged Codex Desktop App use the same per-user `CODEX_HOME`. Admins should
+deploy the overlay to one of these locations:
+
+| Platform | Example path |
+| --- | --- |
+| macOS and Linux | `~/.codex/.env.blackrock-proxy` |
+| Windows | `%USERPROFILE%\.codex\.env.blackrock-proxy` |
+| Custom Codex home | `$CODEX_HOME/.env.blackrock-proxy` |
+
+The Desktop App's bundled Codex backend reads the overlay through the shared startup path. For a
+TUI connected to a remote app-server, the overlay must instead be deployed to the user account and
+`CODEX_HOME` on the machine running the app-server, because that process performs the relevant
+network operations.
+
+On managed macOS devices, administrators can use MDM or Jamf managed-file deployment, or an
+administrator-installed package that targets each user's Codex home. On Windows, Group Policy
+Preferences or Intune can create the per-user `.codex` directory and copy the overlay while running
+in the user's context. Deployment does not require the user to run a script or launch Codex from a
+terminal. Codex must be fully restarted after deployment or after the user changes networks.
+
+This is a user-level startup file, not an enforced managed-policy location. The initial
+implementation does not verify a signature or prevent the user from modifying the overlay; MDM or
+GPO controls delivery only. If the file must be tamper-resistant or server-authenticated, that
+requires a separate managed-file location and signature-verification design. `CODEX_HOME` must also
+be established before Codex starts and cannot be selected from `.env` or `.env.*` itself.
+
+## Blackrock MVP
+
+The Blackrock MVP has one purpose: enable the corporate proxy when its TCP endpoint is reachable
+from the device, and remove the proxy environment variables when that endpoint is unreachable. The
+proxy is required only while the device is on the corporate network.
+
+### Required condition and actions
+
+The MVP needs only the `tcp_connect` condition and a direct negation of that condition. It does not
+need `file_exists`, `env_equals`, `os`, `all`, `any`, or arbitrarily nested condition trees. The two
+supported condition shapes are:
+
+```json
+{"type":"tcp_connect","host":"proxy.example.com","port":8080,"timeout_ms":500}
+{"not":{"type":"tcp_connect","host":"proxy.example.com","port":8080,"timeout_ms":500}}
+```
+
+The positive condition may also use `from` to read a proxy URL from an assignment in the same
+overlay. This preserves the documented proxy configuration without duplicating the endpoint:
+
+```json
+{"type":"tcp_connect","from":"HTTPS_PROXY","timeout_ms":500}
+```
+
+When an overlay condition passes, Codex must support both actions already defined by this format:
+
+- Remove each variable named by `# codex-env-unset`.
+- Apply the overlay's dotenv assignments after the removals.
+
+A failing condition makes no changes. Set and unset operations must both continue to reject names
+beginning with `CODEX_`, compared case-insensitively.
+
+### Blackrock deployment
+
+With the current apply-on-match semantics, setting variables on a successful check and unsetting
+them on a failed check requires two mutually exclusive overlays. For example, the on-network
+overlay can be deployed as `.env.10-blackrock-proxy-on`:
+
+```dotenv
+# codex-env-if: {"type":"tcp_connect","from":"HTTPS_PROXY","timeout_ms":500}
+
+HTTPS_PROXY=http://proxy.example.com:8080
+HTTP_PROXY=http://proxy.example.com:8080
+ALL_PROXY=http://proxy.example.com:8080
+NO_PROXY=localhost,127.0.0.1,.example.com
+```
+
+The off-network overlay can be deployed as `.env.20-blackrock-proxy-off`:
+
+```dotenv
+# codex-env-if: {"not":{"type":"tcp_connect","host":"proxy.example.com","port":8080,"timeout_ms":500}}
+# codex-env-unset: ["HTTPS_PROXY","HTTP_PROXY","ALL_PROXY","NO_PROXY"]
+```
+
+The managed deployment must replace the example endpoint and variable list with the actual
+Blackrock proxy configuration. It should include every proxy variable that the deployment may set
+or inherit and that must not remain active off the corporate network.
+
+The resulting behavior is:
+
+| Device network | Positive overlay | Negative overlay | Final proxy environment |
+| --- | --- | --- | --- |
+| Corporate proxy reachable | Sets the managed proxy values | Makes no changes | Proxy variables are present |
+| Corporate proxy unreachable | Makes no changes | Removes the managed proxy names | Proxy variables are absent |
+
+Each overlay is evaluated independently, so this two-file configuration performs two TCP checks at
+startup. If deployment must use exactly one managed file and one TCP check, the format needs an
+explicit false-branch action such as `unset-if-false`; the current format does not provide one.
+
+### Defensive behavior retained for the MVP
+
+The narrowed implementation must retain the defenses that apply to TCP-based overlays:
+
+- Run during single-threaded startup, before network clients, workers, sessions, or Tokio are
+  created.
+- Discover overlays only in the startup `CODEX_HOME`, process them in deterministic filename order,
+  and do not let `.env` or an overlay redirect further discovery.
+- Parse conditions and dotenv assignments before applying them. Invalid overlays fail closed, emit
+  a warning without exposing environment values or proxy credentials, and do not prevent other
+  overlays from being considered.
+- Use a default TCP connection timeout, enforce a small maximum timeout, and share the timeout
+  budget across all resolved socket addresses for one check.
+- Continue filtering `CODEX_` names for both set and unset actions.
+- Evaluate conditions only once per process; moving between networks requires a full Codex restart.
+
+The connection timeout does not bound synchronous DNS resolution. A hostname lookup can therefore
+take longer than `timeout_ms`; an IP address should be used when the probe needs a strict total time
+bound.
+
+### MVP validation
+
+Validation should exercise the complete Blackrock behavior rather than the deferred general
+condition engine:
+
+1. Start Codex with the proxy reachable and verify that all managed proxy variables have the
+   configured values before any network client is initialized.
+2. Start Codex with the proxy unreachable and inherited proxy variables present, then verify that
+   every managed proxy variable is absent.
+3. Verify the default and maximum TCP timeout behavior.
+4. Verify that malformed conditions fail closed and that `CODEX_` variables cannot be set or unset.
+5. Repeat the on-network and off-network checks with a full process restart between them.