feat: normalize, resolve, and build canonical command identity

[AlexAlves87]

Summary

Adds the normalization and resolution stage of the exec approval pipeline. Given a validated argv, this stage detects whether the command is a shell wrapper, resolves the executable to its full path, and produces a canonical identity that downstream evaluation consumes as the single source of truth. Nothing from this point forward re-examines the raw request directly.

Why

The macOS pipeline separates validation from normalization deliberately: validation rejects malformed input early, normalization produces a stable identity for all downstream consumers. Without this stage, each downstream module would need its own resolution logic — inconsistent semantics, duplicated shell-wrapper detection, and no single place to apply fail-closed policy on ambiguous inputs.

ResolveForAllowlist is fail-closed on command substitution, -EncodedCommand aliases, env with modifying flags or assignments before a shell wrapper, unclosed quotes, and paths with non-standard : positions.

What changed

• ExecShellWrapperNormalizer — single-level wrapper detection on argv (bash, sh, zsh, cmd, powershell, pwsh); recursively unwraps transparent env prefixes up to depth 4
• ExecEnvInvocationUnwrapper — strips env [OPTIONS] [VAR=VAL...] COMMAND to surface the real executable; fail-closed on unknown flags
• ExecCommandResolver — three resolution functions with distinct semantics: singular for the state machine, multi-segment fail-closed for allowlist matching, and pattern suggestions for the prompt UI
• CanonicalCommandIdentity — the type that replaces the raw request as input to all downstream modules
• ExecApprovalV2Normalizer — orchestrates the three steps and issues a stable resolution-failed denial when resolution is impossible

What's NOT in scope

• Evaluation (state machine, allowlist matching) — next module
• Prompting — depends on evaluation being stable
• Integration with HandleRunAsync — deferred until evaluation and prompting are complete

Test Status

• OpenClaw.Shared.Tests — 1,215 passed, 20 skipped, 0 failed
• OpenClaw.Tray.Tests — 406 passed, 0 failed

Co-Authored-By: Claude Sonnet 4.6 noreply@anthropic.com

[shanselman]

Hi @AlexAlves87 — Copilot here, commenting on Scott's behalf.

First: this is very much the right direction. The shape of this PR makes sense to me: Windows is catching up to the macOS exec-approval pipeline by separating validation → normalization/resolution → evaluation/prompting/wiring, and CanonicalCommandIdentity is the right kind of boundary so downstream code does not keep re-parsing raw argv in slightly different ways.

I did a deeper/adversarial pass because this layer is going to become security-policy infrastructure once the later coordinator/evaluator PRs wire it in. I think the architecture is good, and I also think we should tighten a few fail-closed cases before merging so we do not bake in bypass semantics.

The specific issues I found:

1. PowerShell -EncodedCommand detection needs to be stricter.
   The PR says ResolveForAllowlist fails closed on -EncodedCommand aliases, which is exactly the right policy. The current scanner looks too literal, though. Please add coverage/fixes for forms PowerShell accepts, including:

   • quoted flags: powershell "-enc" <payload>
   • colon/equals forms: -EncodedCommand:<payload>, -enc:<payload>, -enc=<payload>
   • accepted abbreviations / unique prefixes such as -encod, -encode, etc.
   • direct top-level powershell / pwsh invocations, not only PowerShell found inside a shell-wrapper segment

   If any of these are present, allowlist resolution should return no satisfiable resolution / fail closed rather than treating powershell itself as the allowlisted executable.

2. env modifiers should fail closed unless the effective environment is modeled exactly.
   Cases like env PATH=... command, env -i ..., env -uFOO ..., env --chdir=... ..., or unknown env flags can change what actually executes. If normalization resolves using the caller/process environment while the command executes under a modified environment, allowlist matching can approve the wrong executable. I would prefer this layer fail closed for env modifiers in allowlist resolution unless it applies the parsed env changes to the resolution environment exactly.

   One edge case to test: unknown env flags before a shell wrapper, e.g. env --bogus bash -c .... That should not degrade into “resolve/allow env itself.”

3. Path/token parsing hardening before this becomes live.
   These are less urgent than the two above, but still worth fixing while this code is fresh:

   • guard Path.GetFullPath, Path.IsPathFullyQualified, Path.Combine, Path.GetFileName, etc. so hostile/odd argv returns a typed resolution failure instead of throwing
   • avoid returning non-executable no-extension PATH shadows before checking PATHEXT candidates on Windows
   • improve first-token parsing around partial quoted tokens like "foo".exe or "C:\Program Files\Git\bin\git".exe
   • tighten colon handling so drive-letter paths require an actual drive letter, and extended-length paths like \\?\C:\... are handled deliberately

I am not reading this as a reject. Quite the opposite: this PR is a strong foundation and looks like the right continuation of #244. I just think the normalization layer is the security boundary for the next set of PRs, so the fail-closed claims should be airtight before we take it.

Suggested next step: add regression tests for the -EncodedCommand and env cases above, make those cases fail closed, and then this should be much closer to mergeable.

[AlexAlves87]

Thanks to @shanselman and the Copilot review bot for the detailed security findings on #260 — each addressed as a separate atomic commit below.

Finding #1 — -EncodedCommand bypass via direct invocation (99cc2a9)
DirectExecUsesEncodedCommand now catches ["powershell", "-enc", …] and env-transparent forms. IsEncodedCommandFlag recognizes -ec, -enc, -encodedcommand, abbreviations (-enco…), and separator forms (-enc=…, -enc:…). Closes the direct-exec gap the segment scanner didn't cover.

Finding #2 — env with modifiers not fail-closed (c449357)
ResolveForAllowlist now checks HasModifiers before any unwrap attempt. Catches env --unknown-flag bash -c … and env VAR=val … before resolution.

Finding #3 — path and token parsing hardening (412eb40)
ParseFirstToken is fail-closed on unclosed quotes and preserves suffix after closing quote ("git".exe → git.exe). HasNonStandardColon handles \?\ extended-length paths and requires char.IsAsciiLetter at the drive position. FindInPath probes PATHEXT before the bare name (Windows CreateProcess order).

14 new/updated tests cover the added surface including equals form, env with unknown flags, extended-length paths, and quoted paths with spaces.