Add manifest environment access policy

[leynos]

Summary

Add manifest-level access control for environment variables read through the
Jinja env() helper. The control must be enforced at env() call time in
src/manifest/env_reader.rs, before a blocked lookup can return a process
environment value.

This reduces secret ingress into rendered manifest fields. It does not make
rendered manifest contents inherently safe to log: any value that is allowed
and rendered still needs the existing output and logging discipline.

Thanks to @benrrr56-wq for the nudge here — a little bouncer for env() seems
like a very sensible addition.

Proposed configuration and policy shape

Follow the named-policy idiom used by NetworkPolicy in
src/stdlib/network/policy/mod.rs and its CliConfig wiring. Introduce a
purpose-specific environment-access policy, constructed from the effective CLI
configuration and supplied to manifest loading; do not model this as a
PolicyDefinition<T> tri-state.

Add these appendable CliConfig fields, with the corresponding normal
configuration, environment, and CLI sources generated by the existing config
machinery:

# netsuke.toml (or another supported Netsuke configuration layer)
env_allow_var = ["CI", "PACKAGE_REGISTRY_TOKEN"]
env_block_var = ["AWS_SECRET_ACCESS_KEY", "GITHUB_TOKEN"]

The public spellings should be NETSUKE_ENV_ALLOW_VAR and
NETSUKE_ENV_BLOCK_VAR for environment configuration, and
--env-allow-var NAME and --env-block-var NAME for CLI configuration. Each
entry is one exact environment-variable name; no glob or pattern matching is
introduced by this ticket. The sample configuration and generated CLI help must
document the same syntax.

The policy must be default-allow for compatibility: when neither list is
configured, every variable retains today's env() behaviour. An allowlist
becomes restrictive only when it contains at least one entry: then only listed
variables may resolve, subject to the denylist. A denylist without an allowlist
blocks only its listed variables. This preserves existing manifests unchanged
by default, avoids a breaking migration, and lets maintainers adopt explicit
allow rules incrementally. A future default-deny migration would require a
separate, versioned compatibility plan; it is out of scope here.

When both lists apply to the same variable, the denylist wins, matching the
NetworkPolicy precedent that blocked hosts are denied even when allowed
elsewhere. Evaluate the block-list before returning a value, and keep list
contents out of user-facing diagnostics and trace fields.

Blocked-access diagnostics

A blocked env() access must fail with a new fixed-text, localised manifest
diagnostic (for example, manifest.env.blocked). Match the no-name pattern of
manifest.env.missing and manifest.env.invalid_utf8:

• do not include the requested variable name or a value in the error;
• do not interpolate the variable name into the log message or tracing fields;
• emit only a bounded trace such as
  tracing::debug!(failure_kind = "blocked", "manifest env lookup failed").

The Jinja template location remains sufficient to identify the failed env()
call without turning credentials or their names into diagnostic data.

Acceptance criteria

• A named environment-access policy is wired from CliConfig into manifest
  loading and enforced in src/manifest/env_reader.rs at every env()
  call.
• env_allow_var and env_block_var have the documented TOML,
  NETSUKE_..., and CLI spellings; their entries are exact variable names.
• With neither list configured, env() remains default-allow so existing
  manifests do not need migration.
• A non-empty allowlist enables default-deny for names outside that list;
  a denylist alone blocks only its entries.
• A matching deny rule always overrides a matching allow rule.
• A permitted variable resolves successfully through env().
• A denied variable is blocked with a bounded, value-free, name-free error
  and failure_kind = "blocked" trace; tests prove neither the variable
  name nor its value reaches either diagnostic surface.
• Existing missing and invalid-UTF-8 diagnostics retain their fixed-text,
  no-name behaviour.
• Documentation explains that this is secret-ingress reduction, not a
  guarantee that rendered manifest content is safe to log.
• Relevant unit, integration, and documentation gates pass.

Relationship to #644 and Phases 1 to 3

This is defence in depth alongside #644,
which prevents project configuration from widening trusted fetch policy. It
addresses a different boundary: which host-environment values a manifest may
bring into rendered fields.

It does not replace, weaken, or reopen the removal of unsafe AST-dump logging
delivered by Phases 1 to 3. That remediation remains required independently;
this policy merely reduces the set of secrets that can enter rendered manifest
fields in the first place.

References

• Prevent project configuration from widening trusted fetch policy #644: Prevent project configuration from widening trusted fetch policy #644

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Add an exact-name, default-allow EnvAccessPolicy modelled on NetworkPolicy, with block-overrides-allow precedence and no glob support.
• Enforce the policy inside env_var_with in src/manifest/env_reader.rs, before the reader runs, and map a block to a new fixed-text manifest.env.blocked diagnostic with a bounded failure_kind = "blocked" trace.
• Wire env_allow_var/env_block_var through Clap, CliConfig, the merge pipeline, and Cli::env_access_policy(), then thread the policy through the runner into manifest loading exactly as NetworkPolicy flows today.
• Add localisation entries in every locale, document the secret-ingress caveat, and add unit, integration, BDD, and CLI tests, then regenerate the affected snapshots.

Design Choices

Design Choice 1: Where must the policy check run so that "block before return" holds for env()?

Options Considered:

1. Evaluate the policy inside the env() closure in from_str_named, before calling env_var_with.
2. Pass the policy into env_var_with and evaluate it there, before calling the injected reader.

Chosen Option: 2

Rationale: It keeps all env() enforcement, error mapping, and bounded tracing in src/manifest/env_reader.rs, as the ticket directs, and keeps the blocked diagnostic beside the existing missing/invalid-UTF-8 paths.

Design Choice 2: Should the policy also reach StdlibConfig, or only ManifestParse?

Options Considered:

1. Thread the policy only through ManifestParse, since env() is the sole enforcement point in scope.
2. Add the policy to both ManifestParse and StdlibConfig, mirroring network_policy.

Chosen Option: 1

Rationale: The ticket scope is the env() helper only. Add the policy to ManifestParse, where the env() closure is built, and avoid unused surface in StdlibConfig.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Define the environment-access policy and its blocked diagnostic

Create the policy type and the new manifest diagnostic. Group these together because the policy's blocked outcome must map to the new diagnostic. Model the policy on NetworkPolicy, but restrict it to exact variable-name matching with no glob or pattern support.

Task 1: Add the EnvAccessPolicy type

Create a purpose-specific, default-allow policy with exact-name allow and block lists.

• Create a new module for the policy, for example src/manifest/env_policy/mod.rs, and re-export the type from src/manifest/mod.rs.
• Model the type on NetworkPolicy in src/stdlib/network/policy/mod.rs, but store two Vec<String> (or BTreeSet<String>) collections of exact variable names: an allow list and a block list.
• Make the type Clone + PartialEq + Eq with a Default that is fully permissive (both lists empty).
• Add builder methods allow_var/allow_vars and block_var/block_vars that append exact names. Do not add glob or pattern parsing.
• Add pub fn evaluate(&self, name: &str) -> Result<(), EnvPolicyViolation> with this precedence: if the block list contains name, return the blocked violation; else, if the allow list is non-empty and does not contain name, return the blocked violation; else return Ok(()).
• Keep the default-allow semantics explicit: an empty allow list means every name passes unless it is in the block list.
• Define an EnvPolicyViolation enum with a single Blocked variant carrying a LocalizedMessage, following the NetworkPolicyViolation shape. Do not embed the variable name in the message.

Task 2: Add the manifest.env.blocked diagnostic key

Register the new localisation key so the blocked violation resolves to fixed text.

• Add MANIFEST_ENV_BLOCKED => "manifest.env.blocked", to the define_keys! macro in src/localization/keys.rs, next to MANIFEST_ENV_MISSING and MANIFEST_ENV_INVALID_UTF8.
• Reference keys::MANIFEST_ENV_BLOCKED from the EnvPolicyViolation::Blocked message, with no interpolated arguments, matching the fixed-text pattern of the sibling keys.

🤖 Prompt for AI agents

Implement Phase 1: define the environment-access policy type and its
localisation diagnostic.

- Create a new module for the policy, for example
`src/manifest/env_policy/mod.rs`, and re-export the type from
`src/manifest/mod.rs`. Model it on `NetworkPolicy` in
`src/stdlib/network/policy/mod.rs`, but store exact variable names in two
collections (allow list and block list, e.g. `Vec<String>` or
`BTreeSet<String>`). Do not add glob or pattern parsing.
- Make the type `Clone + PartialEq + Eq` with a `Default` that is fully
permissive (both lists empty).
- Add builder methods `allow_var`/`allow_vars` and `block_var`/`block_vars` that
append exact names.
- Implement `pub fn evaluate(&self, name: &str) -> Result<(),
EnvPolicyViolation>` with block-overrides-allow precedence: block list match
returns blocked; non-empty allow list without a match returns blocked; otherwise
return `Ok(())`. Keep the default-allow semantics explicit for empty lists.
- Define `EnvPolicyViolation` with a single `Blocked` variant carrying a
`LocalizedMessage`, following the shape of `NetworkPolicyViolation`. Do not
embed the variable name in the message.
- Add `MANIFEST_ENV_BLOCKED => "manifest.env.blocked",` to the `define_keys!`
macro in `src/localization/keys.rs`, next to `MANIFEST_ENV_MISSING` and
`MANIFEST_ENV_INVALID_UTF8`. Reference `keys::MANIFEST_ENV_BLOCKED` from
`EnvPolicyViolation::Blocked` with no interpolated arguments.

Phase 2: Enforce the policy in env_reader.rs and thread it into manifest loading

Wire the policy into the env() call path so enforcement happens before any process lookup returns a value. Thread the policy through the private manifest bundle and the on-disk load path.

Task 1: Enforce the policy in env_var_with

Evaluate the policy before the reader runs, and map a block to the new diagnostic.

• Update env_var_with in src/manifest/env_reader.rs to accept the EnvAccessPolicy (by reference) in addition to the reader.
• Evaluate policy.evaluate(name) before calling the injected reader. On a Blocked violation, return early.
• Map the block to a minijinja::Error with ErrorKind::InvalidOperation and the localised text from keys::MANIFEST_ENV_BLOCKED. Do not include the variable name or any value.
• Emit exactly one bounded trace: tracing::debug!(failure_kind = "blocked", "manifest env lookup failed"). Do not add the name or value to the trace.
• Keep the existing NotPresent/NotUnicode paths, tracing fields, and error text unchanged.

Task 2: Thread the policy through ManifestParse and the env() registration

Give the env() closure access to the policy at registration time.

• Add an env_access_policy: &'a EnvAccessPolicy field to the private ManifestParse<'a> struct in src/manifest/mod.rs, beside env_reader.
• Update the jinja.add_function("env", ...) closure in from_str_named to capture the policy and pass it into env_var_with.
• Update every construction site of ManifestParse to supply the policy. For read-only or manifest-query paths that already use disabled_env_reader, supply EnvAccessPolicy::default(), since the disabled reader already denies all lookups.

Task 3: Thread the policy through the on-disk load path

Carry the policy from the runner into manifest loading, alongside NetworkPolicy.

• Extend the public on-disk entry points in src/manifest/mod.rs (from_path_with_policy and from_path_with_policy_and_env) and src/manifest/query.rs::from_path_with_policy_and_env to accept and pass an EnvAccessPolicy.
• Extend src/runner/generation.rs::load_manifest_for_build and src/runner/mod.rs::load_manifest_with_stage_reporting to accept and forward the EnvAccessPolicy, mirroring how they forward NetworkPolicy.
• Provide a permissive default at any call site that does not yet supply a policy, to preserve current behaviour.

🤖 Prompt for AI agents

Implement Phase 2: enforce the EnvAccessPolicy inside the env() call path and
thread it through manifest loading.

- Update `env_var_with` in `src/manifest/env_reader.rs` to accept the
`EnvAccessPolicy` by reference alongside the reader. Evaluate
`policy.evaluate(name)` before calling the injected reader, and return early on
a `Blocked` violation.
- Map a block to a `minijinja::Error` with `ErrorKind::InvalidOperation` and the
localised text from `keys::MANIFEST_ENV_BLOCKED`, with no variable name or value
included.
- Emit exactly one bounded trace on block: `tracing::debug!(failure_kind =
"blocked", "manifest env lookup failed")`, with no name or value attached. Leave
the existing `NotPresent`/`NotUnicode` paths, tracing fields, and error text
unchanged.
- Add an `env_access_policy: &'a EnvAccessPolicy` field to the private
`ManifestParse<'a>` struct in `src/manifest/mod.rs`, beside `env_reader`. Update
the `jinja.add_function("env", ...)` closure in `from_str_named` to capture the
policy and pass it into `env_var_with`. Update every `ManifestParse`
construction site to supply the policy; for read-only or manifest-query paths
already using `disabled_env_reader`, supply `EnvAccessPolicy::default()`.
- Extend the public on-disk entry points `from_path_with_policy` and
`from_path_with_policy_and_env` in `src/manifest/mod.rs`, and
`from_path_with_policy_and_env` in `src/manifest/query.rs`, to accept and pass
an `EnvAccessPolicy`.
- Extend `load_manifest_for_build` in `src/runner/generation.rs` and
`load_manifest_with_stage_reporting` in `src/runner/mod.rs` to accept and
forward the `EnvAccessPolicy`, mirroring how they forward `NetworkPolicy`.
Provide a permissive default at any call site not yet supplying a policy, to
preserve current behaviour.

Phase 3: Add CLI and configuration wiring

Add the env_allow_var and env_block_var sources across TOML, NETSUKE_*, and CLI, and construct the policy from the effective configuration. Mirror the fetch_allow_scheme idiom exactly.

Task 1: Declare the CLI flags and config fields

Add the two appendable list fields to both the Clap parser and the layered config.

• Add env_allow_var: Vec<String> and env_block_var: Vec<String> to the Clap Cli struct in src/cli/command.rs, using #[arg(long = "env-allow-var", value_name = "VAR")] and #[arg(long = "env-block-var", value_name = "VAR")]. Use the plain Vec<String> pattern of default_targets; do not add a custom value_parser.
• Add the same two fields to CliConfig in src/cli/config.rs with #[ortho_config(merge_strategy = "append")] and #[serde(default)], mirroring fetch_allow_scheme. This yields TOML keys env_allow_var/env_block_var and env vars NETSUKE_ENV_ALLOW_VAR/NETSUKE_ENV_BLOCK_VAR.
• Add Vec::new() initialisers to the Default implementations for both structs.

Task 2: Bridge the flags through the merge pipeline

Reconcile the parser fields and the layered config fields.

• Add maybe_insert_explicit(matches, "env_allow_var", ...) and maybe_insert_explicit(matches, "env_block_var", ...) in cli_overrides_from_matches in src/cli/merge.rs.
• Copy config.env_allow_var and config.env_block_var back onto the runtime Cli in apply_config.

Task 3: Construct the policy from the effective CLI

Turn the flat fields into an EnvAccessPolicy.

• Add pub fn env_access_policy(&self) -> EnvAccessPolicy to impl Cli in src/cli_policy.rs, following network_policy().
• Build the policy by appending self.env_allow_var to the allow list and self.env_block_var to the block list.
• Call cli.env_access_policy() at the runner dispatch sites that already call cli.network_policy(), and pass the result into the manifest-loading entry points extended in Task 2.3.

🤖 Prompt for AI agents

Implement Phase 3: wire env_allow_var and env_block_var across TOML, NETSUKE_*
environment variables, and CLI flags, mirroring the fetch_allow_scheme idiom
exactly.

- Add `env_allow_var: Vec<String>` and `env_block_var: Vec<String>` to the Clap
`Cli` struct in `src/cli/command.rs`, using `#[arg(long = "env-allow-var",
value_name = "VAR")]` and `#[arg(long = "env-block-var", value_name = "VAR")]`,
following the plain `Vec<String>` pattern of `default_targets` with no custom
`value_parser`.
- Add the same two fields to `CliConfig` in `src/cli/config.rs` with
`#[ortho_config(merge_strategy = "append")]` and `#[serde(default)]`, mirroring
`fetch_allow_scheme`, producing TOML keys `env_allow_var`/`env_block_var` and
env vars `NETSUKE_ENV_ALLOW_VAR`/`NETSUKE_ENV_BLOCK_VAR`. Add `Vec::new()`
initialisers to both `Default` implementations.
- In `cli_overrides_from_matches` in `src/cli/merge.rs`, add
`maybe_insert_explicit(matches, "env_allow_var", ...)` and
`maybe_insert_explicit(matches, "env_block_var", ...)`. In `apply_config`, copy
`config.env_allow_var` and `config.env_block_var` back onto the runtime `Cli`.
- Add `pub fn env_access_policy(&self) -> EnvAccessPolicy` to `impl Cli` in
`src/cli_policy.rs`, following `network_policy()`. Build the policy by appending
`self.env_allow_var` to the allow list and `self.env_block_var` to the block
list.
- Call `cli.env_access_policy()` at the runner dispatch sites that already call
`cli.network_policy()`, and pass the result into the manifest-loading entry
points extended in Phase 2.

Phase 4: Localisation and documentation

Add the required localisation entries for the new help strings and diagnostic, and document the policy with the secret-ingress caveat.

Task 1: Add CLI help localisation keys and translations

Register help keys for the two new flags and add the new diagnostic message to every locale.

• Add CLI_FLAG_ENV_ALLOW_VAR_HELP => "cli.flag.env_allow_var.help", and CLI_FLAG_ENV_BLOCK_VAR_HELP => "cli.flag.env_block_var.help", to src/localization/keys.rs.
• Add the two matching arms to top_level_flag_help_key in src/cli_l10n.rs. This is required so src/cli/release_help.rs does not fail when it walks the new CliConfig fields.
• Add translated entries for cli.flag.env_allow_var.help, cli.flag.env_block_var.help, and manifest.env.blocked to every locales/*/messages.ftl file (all shipped locales). Insert manifest.env.blocked immediately after manifest.env.invalid_utf8. Use fixed text with no placeables for manifest.env.blocked, and translate each entry rather than copy the English text. The build_l10n_audit build step fails if any locale lacks a key.

Task 2: Document the policy and its caveat

Add sample configuration and user-facing documentation.

• Add a commented env_allow_var/env_block_var example block to docs/sample-netsuke.toml, directly beneath the fetch policy block, in the same terse one-comment-per-key style. State that each entry is one exact variable name and that no glob or pattern matching applies.
• Document the CLI spellings --env-allow-var NAME and --env-block-var NAME, the env spellings NETSUKE_ENV_ALLOW_VAR/NETSUKE_ENV_BLOCK_VAR, and the default-allow, allow-list-activates-default-deny, and block-overrides-allow semantics in the relevant user guide (for example docs/stdlib-yaml-and-jinja-guide.md or docs/users-guide.md).
• Add an explicit caveat: this policy reduces secret ingress into rendered manifest fields; it is not a guarantee that rendered manifest content is safe to log. State that allowed and rendered values still require the existing output and logging discipline. Record the remediation in docs/security-network-command-audit.md in the same bullet style used for the network policy finding.

🤖 Prompt for AI agents

Implement Phase 4: add localisation entries for the new CLI help strings and
diagnostic, and document the policy.

- Add `CLI_FLAG_ENV_ALLOW_VAR_HELP => "cli.flag.env_allow_var.help",` and
`CLI_FLAG_ENV_BLOCK_VAR_HELP => "cli.flag.env_block_var.help",` to
`src/localization/keys.rs`. Add matching arms to `top_level_flag_help_key` in
`src/cli_l10n.rs`, required so `src/cli/release_help.rs` does not fail when
walking the new `CliConfig` fields.
- Add translated entries for `cli.flag.env_allow_var.help`,
`cli.flag.env_block_var.help`, and `manifest.env.blocked` to every
`locales/*/messages.ftl` file for all shipped locales. Insert
`manifest.env.blocked` immediately after `manifest.env.invalid_utf8`. Use fixed
text with no placeables for `manifest.env.blocked`, and translate each entry
rather than copying the English text, since `build_l10n_audit` fails the build
if any locale lacks a key.
- Add a commented `env_allow_var`/`env_block_var` example block to
`docs/sample-netsuke.toml`, directly beneath the fetch policy block, in the same
terse one-comment-per-key style, stating that each entry is one exact variable
name with no glob or pattern matching.
- Document the CLI spellings `--env-allow-var NAME` and `--env-block-var NAME`,
the env spellings `NETSUKE_ENV_ALLOW_VAR`/`NETSUKE_ENV_BLOCK_VAR`, and the
default-allow, allow-list-activates-default-deny, and block-overrides-allow
semantics in the relevant user guide (for example
`docs/stdlib-yaml-and-jinja-guide.md` or `docs/users-guide.md`).
- Add an explicit caveat stating that the policy reduces secret ingress into
rendered manifest fields, but is not a guarantee that rendered manifest content
is safe to log, and that allowed and rendered values still require the existing
output and logging discipline. Record the remediation in
`docs/security-network-command-audit.md`, in the same bullet style used for the
network policy finding.

Phase 5: Tests and snapshot updates

Prove the policy behaviour, the name-free diagnostics, and the CLI wiring. Regenerate the affected snapshots.

Task 1: Add policy unit tests

Cover the policy precedence and default-allow semantics.

• Add rstest cases beside the new policy module, mirroring src/stdlib/network/policy/tests.rs.
• Cover: default-allow baseline (empty lists pass all names); a non-empty allow list activates default-deny for names outside it; a block list alone blocks only its entries; a block rule overrides a matching allow rule (block-overrides-allow).
• Assert the EnvPolicyViolation::Blocked variant for each denied case.

Task 2: Add manifest env() blocked tests

Prove the blocked path returns fixed, name-free text and a bounded trace.

• Add a blocked case to the diagnostic tests in tests/manifest_env_tests.rs, reusing manifest_yaml, an injected EnvReader, and a configured EnvAccessPolicy that blocks the requested variable. Assert the error chain contains the fixed blocked substring and never contains the variable name or value.
• Add an insta snapshot test for the localised blocked message, using the en_localizer fixture, matching the existing missing/invalid-UTF-8 snapshot tests.
• Add a unit test in src/manifest/env_reader.rs using with_test_subscriber, following the existing sentinel pattern. Assert an event with failure_kind = "blocked" exists and that a credential-like sentinel name never appears in any captured event or in the returned Jinja error text.
• Confirm the existing missing and invalid-UTF-8 tests still pass unchanged, to satisfy the "retain fixed-text, no-name behaviour" criterion.

Task 3: Add BDD coverage

Add an integration scenario for a blocked variable.

• Add a scenario to tests/features/manifest.feature for a variable blocked by policy, mirroring the existing undefined-variable scenario.
• Add the supporting Given/Then steps in tests/bdd/steps/manifest/environment.rs, configuring the EnvAccessPolicy and asserting the blocked, name-free failure.

Task 4: Add CLI/config tests and regenerate snapshots

Cover parsing, precedence, and env-var override for the new flags, and update generated help.

• Mirror the fetch_allow_scheme cases in tests/cli_tests/parsing.rs, merge.rs, config_discovery_overrides.rs, and merge_precedence_proptests.rs: repeatable CLI flags, TOML precedence, NETSUKE_ENV_ALLOW_VAR/NETSUKE_ENV_BLOCK_VAR env override, and append-merge across layers.
• Regenerate and accept the affected snapshots: tests/snapshots/release_help/*, the CLI help snapshots under src/snapshots/cli/*, and the OrthoConfig metadata snapshot, since these enumerate all CliConfig fields and rendered help.

🤖 Prompt for AI agents

Implement Phase 5: add tests for the policy, the blocked diagnostic, BDD
coverage, and CLI wiring, then regenerate snapshots.

- Add rstest cases beside the new policy module, mirroring
`src/stdlib/network/policy/tests.rs`. Cover the default-allow baseline (empty
lists pass all names), a non-empty allow list activating default-deny for names
outside it, a block list alone blocking only its entries, and
block-overrides-allow when a block rule matches an allowed name. Assert the
`EnvPolicyViolation::Blocked` variant for each denied case.
- Add a blocked case to `tests/manifest_env_tests.rs`, reusing `manifest_yaml`,
an injected `EnvReader`, and a configured `EnvAccessPolicy` that blocks the
requested variable. Assert the error chain contains the fixed blocked substring
and never contains the variable name or value. Add an `insta` snapshot test for
the localised blocked message using the `en_localizer` fixture, matching the
existing missing/invalid-UTF-8 snapshot tests.
- Add a unit test in `src/manifest/env_reader.rs` using `with_test_subscriber`,
following the existing sentinel pattern: assert an event with `failure_kind =
"blocked"` exists, and that a credential-like sentinel name never appears in any
captured event or in the returned Jinja error text. Confirm the existing missing
and invalid-UTF-8 tests still pass unchanged.
- Add a scenario to `tests/features/manifest.feature` for a variable blocked by
policy, mirroring the existing undefined-variable scenario, with supporting
`Given`/`Then` steps in `tests/bdd/steps/manifest/environment.rs` that configure
the `EnvAccessPolicy` and assert the blocked, name-free failure.
- Mirror the `fetch_allow_scheme` cases in `tests/cli_tests/parsing.rs`,
`merge.rs`, `config_discovery_overrides.rs`, and
`merge_precedence_proptests.rs`: repeatable CLI flags, TOML precedence,
`NETSUKE_ENV_ALLOW_VAR`/`NETSUKE_ENV_BLOCK_VAR` env override, and append-merge
across layers.
- Regenerate and accept the affected snapshots:
`tests/snapshots/release_help/*`, the CLI help snapshots under
`src/snapshots/cli/*`, and the OrthoConfig metadata snapshot, since these
enumerate all `CliConfig` fields and rendered help.

Research

Netsuke reads process environment variables for manifests through the Jinja env() helper. The helper is registered in src/manifest/mod.rs::from_str_named, which builds a MiniJinja Environment and captures an EnvReader from the private ManifestParse bundle. src/manifest/env_reader.rs defines EnvReader, EnvReadError, process_env_reader, disabled_env_reader, and env_var_with. env_var_with maps NotPresent/NotUnicode to localised, name-free minijinja::Error values and emits one bounded tracing::debug! field.

The NetworkPolicy in src/stdlib/network/policy/mod.rs is the established named-policy idiom: a builder struct with allow/block collections, an evaluate method, and thiserror-derived error enums with LocalizedMessage fields. It flows from CLI flags (fetch_allow_*) declared in src/cli/command.rs and src/cli/config.rs, is constructed by Cli::network_policy() in src/cli_policy.rs, and is threaded through src/runner/* into manifest::from_path_with_policy* and StdlibConfig. Localisation keys live in src/localization/keys.rs with per-locale entries in locales/*/messages.ftl, enforced at build time by build_l10n_audit.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: define the environment-access policy type and its
localisation diagnostic.

- Create a new module for the policy, for example
`src/manifest/env_policy/mod.rs`, and re-export the type from
`src/manifest/mod.rs`. Model it on `NetworkPolicy` in
`src/stdlib/network/policy/mod.rs`, but store exact variable names in two
collections (allow list and block list, e.g. `Vec<String>` or
`BTreeSet<String>`). Do not add glob or pattern parsing.
- Make the type `Clone + PartialEq + Eq` with a `Default` that is fully
permissive (both lists empty).
- Add builder methods `allow_var`/`allow_vars` and `block_var`/`block_vars` that
append exact names.
- Implement `pub fn evaluate(&self, name: &str) -> Result<(),
EnvPolicyViolation>` with block-overrides-allow precedence: block list match
returns blocked; non-empty allow list without a match returns blocked; otherwise
return `Ok(())`. Keep the default-allow semantics explicit for empty lists.
- Define `EnvPolicyViolation` with a single `Blocked` variant carrying a
`LocalizedMessage`, following the shape of `NetworkPolicyViolation`. Do not
embed the variable name in the message.
- Add `MANIFEST_ENV_BLOCKED => "manifest.env.blocked",` to the `define_keys!`
macro in `src/localization/keys.rs`, next to `MANIFEST_ENV_MISSING` and
`MANIFEST_ENV_INVALID_UTF8`. Reference `keys::MANIFEST_ENV_BLOCKED` from
`EnvPolicyViolation::Blocked` with no interpolated arguments.
===============================================================================

Task: 2

Implement Phase 2: enforce the EnvAccessPolicy inside the env() call path and
thread it through manifest loading.

- Update `env_var_with` in `src/manifest/env_reader.rs` to accept the
`EnvAccessPolicy` by reference alongside the reader. Evaluate
`policy.evaluate(name)` before calling the injected reader, and return early on
a `Blocked` violation.
- Map a block to a `minijinja::Error` with `ErrorKind::InvalidOperation` and the
localised text from `keys::MANIFEST_ENV_BLOCKED`, with no variable name or value
included.
- Emit exactly one bounded trace on block: `tracing::debug!(failure_kind =
"blocked", "manifest env lookup failed")`, with no name or value attached. Leave
the existing `NotPresent`/`NotUnicode` paths, tracing fields, and error text
unchanged.
- Add an `env_access_policy: &'a EnvAccessPolicy` field to the private
`ManifestParse<'a>` struct in `src/manifest/mod.rs`, beside `env_reader`. Update
the `jinja.add_function("env", ...)` closure in `from_str_named` to capture the
policy and pass it into `env_var_with`. Update every `ManifestParse`
construction site to supply the policy; for read-only or manifest-query paths
already using `disabled_env_reader`, supply `EnvAccessPolicy::default()`.
- Extend the public on-disk entry points `from_path_with_policy` and
`from_path_with_policy_and_env` in `src/manifest/mod.rs`, and
`from_path_with_policy_and_env` in `src/manifest/query.rs`, to accept and pass
an `EnvAccessPolicy`.
- Extend `load_manifest_for_build` in `src/runner/generation.rs` and
`load_manifest_with_stage_reporting` in `src/runner/mod.rs` to accept and
forward the `EnvAccessPolicy`, mirroring how they forward `NetworkPolicy`.
Provide a permissive default at any call site not yet supplying a policy, to
preserve current behaviour.
===============================================================================

Task: 3

Implement Phase 3: wire env_allow_var and env_block_var across TOML, NETSUKE_*
environment variables, and CLI flags, mirroring the fetch_allow_scheme idiom
exactly.

- Add `env_allow_var: Vec<String>` and `env_block_var: Vec<String>` to the Clap
`Cli` struct in `src/cli/command.rs`, using `#[arg(long = "env-allow-var",
value_name = "VAR")]` and `#[arg(long = "env-block-var", value_name = "VAR")]`,
following the plain `Vec<String>` pattern of `default_targets` with no custom
`value_parser`.
- Add the same two fields to `CliConfig` in `src/cli/config.rs` with
`#[ortho_config(merge_strategy = "append")]` and `#[serde(default)]`, mirroring
`fetch_allow_scheme`, producing TOML keys `env_allow_var`/`env_block_var` and
env vars `NETSUKE_ENV_ALLOW_VAR`/`NETSUKE_ENV_BLOCK_VAR`. Add `Vec::new()`
initialisers to both `Default` implementations.
- In `cli_overrides_from_matches` in `src/cli/merge.rs`, add
`maybe_insert_explicit(matches, "env_allow_var", ...)` and
`maybe_insert_explicit(matches, "env_block_var", ...)`. In `apply_config`, copy
`config.env_allow_var` and `config.env_block_var` back onto the runtime `Cli`.
- Add `pub fn env_access_policy(&self) -> EnvAccessPolicy` to `impl Cli` in
`src/cli_policy.rs`, following `network_policy()`. Build the policy by appending
`self.env_allow_var` to the allow list and `self.env_block_var` to the block
list.
- Call `cli.env_access_policy()` at the runner dispatch sites that already call
`cli.network_policy()`, and pass the result into the manifest-loading entry
points extended in Phase 2.
===============================================================================

Task: 4

Implement Phase 4: add localisation entries for the new CLI help strings and
diagnostic, and document the policy.

- Add `CLI_FLAG_ENV_ALLOW_VAR_HELP => "cli.flag.env_allow_var.help",` and
`CLI_FLAG_ENV_BLOCK_VAR_HELP => "cli.flag.env_block_var.help",` to
`src/localization/keys.rs`. Add matching arms to `top_level_flag_help_key` in
`src/cli_l10n.rs`, required so `src/cli/release_help.rs` does not fail when
walking the new `CliConfig` fields.
- Add translated entries for `cli.flag.env_allow_var.help`,
`cli.flag.env_block_var.help`, and `manifest.env.blocked` to every
`locales/*/messages.ftl` file for all shipped locales. Insert
`manifest.env.blocked` immediately after `manifest.env.invalid_utf8`. Use fixed
text with no placeables for `manifest.env.blocked`, and translate each entry
rather than copying the English text, since `build_l10n_audit` fails the build
if any locale lacks a key.
- Add a commented `env_allow_var`/`env_block_var` example block to
`docs/sample-netsuke.toml`, directly beneath the fetch policy block, in the same
terse one-comment-per-key style, stating that each entry is one exact variable
name with no glob or pattern matching.
- Document the CLI spellings `--env-allow-var NAME` and `--env-block-var NAME`,
the env spellings `NETSUKE_ENV_ALLOW_VAR`/`NETSUKE_ENV_BLOCK_VAR`, and the
default-allow, allow-list-activates-default-deny, and block-overrides-allow
semantics in the relevant user guide (for example
`docs/stdlib-yaml-and-jinja-guide.md` or `docs/users-guide.md`).
- Add an explicit caveat stating that the policy reduces secret ingress into
rendered manifest fields, but is not a guarantee that rendered manifest content
is safe to log, and that allowed and rendered values still require the existing
output and logging discipline. Record the remediation in
`docs/security-network-command-audit.md`, in the same bullet style used for the
network policy finding.
===============================================================================

Task: 5

Implement Phase 5: add tests for the policy, the blocked diagnostic, BDD
coverage, and CLI wiring, then regenerate snapshots.

- Add rstest cases beside the new policy module, mirroring
`src/stdlib/network/policy/tests.rs`. Cover the default-allow baseline (empty
lists pass all names), a non-empty allow list activating default-deny for names
outside it, a block list alone blocking only its entries, and
block-overrides-allow when a block rule matches an allowed name. Assert the
`EnvPolicyViolation::Blocked` variant for each denied case.
- Add a blocked case to `tests/manifest_env_tests.rs`, reusing `manifest_yaml`,
an injected `EnvReader`, and a configured `EnvAccessPolicy` that blocks the
requested variable. Assert the error chain contains the fixed blocked substring
and never contains the variable name or value. Add an `insta` snapshot test for
the localised blocked message using the `en_localizer` fixture, matching the
existing missing/invalid-UTF-8 snapshot tests.
- Add a unit test in `src/manifest/env_reader.rs` using `with_test_subscriber`,
following the existing sentinel pattern: assert an event with `failure_kind =
"blocked"` exists, and that a credential-like sentinel name never appears in any
captured event or in the returned Jinja error text. Confirm the existing missing
and invalid-UTF-8 tests still pass unchanged.
- Add a scenario to `tests/features/manifest.feature` for a variable blocked by
policy, mirroring the existing undefined-variable scenario, with supporting
`Given`/`Then` steps in `tests/bdd/steps/manifest/environment.rs` that configure
the `EnvAccessPolicy` and assert the blocked, name-free failure.
- Mirror the `fetch_allow_scheme` cases in `tests/cli_tests/parsing.rs`,
`merge.rs`, `config_discovery_overrides.rs`, and
`merge_precedence_proptests.rs`: repeatable CLI flags, TOML precedence,
`NETSUKE_ENV_ALLOW_VAR`/`NETSUKE_ENV_BLOCK_VAR` env override, and append-merge
across layers.
- Regenerate and accept the affected snapshots:
`tests/snapshots/release_help/*`, the CLI help snapshots under
`src/snapshots/cli/*`, and the OrthoConfig metadata snapshot, since these
enumerate all `CliConfig` fields and rendered help.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---