microsoft / microsoft/aspire

Sign and bundle hex1bpty.exe for AppHost-owned terminals

Open
#19,976 1 comment 0 reactions 1 assignee Claimed by @mitchdenny View on GitHub
needs-area-label
Dominant language
C#
Stars
6.3k
Forks
991
Avg merge
2d 15h
Merged PRs (30d)
196

Description

### Is there an existing issue for this?

- [x] I have searched the existing issues

### Is your feature request related to a problem? Please describe the problem.

The AppHost-owned terminal experiences in #19887 use Hex1b to launch interactive child processes. On Windows, this requires `hex1bpty.exe`. Official Aspire bundles need to distribute a Microsoft Authenticode-signed copy, and AppHosts must locate and execute that copy.

The current build deliberately removes this helper from `src/` publish outputs unless `PublishHex1bPtyHost=true` (#19554). `CreateLayout.CopyManaged` also copies only `aspire-managed.exe` and dashboard assets, excluding other executables. Existing signing configuration covers `Hex1b.dll`, but not `hex1bpty.exe`.

Hex1b's default helper discovery searches the executing application's `AppContext.BaseDirectory`, not the Aspire installation or the .NET single-file extraction directory. Merely adding the executable to the bundle will not redirect separately launched C# AppHosts to the signed copy.

### Describe the solution you'd like

1. **Stage the correct Windows helper.** Use the existing Hex1b NuGet native asset for each target RID (`win-x64` and `win-arm64`), not the build machine's architecture. Opt `Aspire.Managed` into publishing it and explicitly keep it outside the managed single-file executable. Do not mutate the NuGet cache.
2. **Sign during Aspire bundle preparation.** Add a `FileSignInfo` mapping for `hex1bpty.exe` using `3PartySHA2`, plus an `ItemsToSign` entry for the staged/published executable in `eng/Signing.props`. Use the existing pre-bundle signing step alongside `aspire-managed.exe`.
3. **Include the signed copy in the bundle.** Update `tools/CreateLayout/Program.cs` to place it at `managed/hex1bpty.exe`, alongside `aspire-managed.exe`. Preserve the ordering: publish/stage → sign both executables → create bundle archive → embed and sign the CLI. Avoid an unnecessary duplicate helper in the CLI's top-level publish output.
4. **Wire runtime discovery.** Resolve the helper from the active bundle layout using shared CLI/SDK bundle-path plumbing, including separately launched C# AppHosts. Pass its absolute path through `Hex1bTerminalProcessOptions.WindowsPtyHostPath` in `TerminalService.CreateBuilder`. Keep this internal to Aspire. Bundle mode must use the selected helper rather than silently falling back to an unsigned NuGet copy; non-bundle development can retain normal Hex1b discovery.

Acceptance criteria:

- Official Windows x64 and ARM64 bundles contain the matching helper with a valid Microsoft Authenticode signature after extraction.
- AppHost-owned terminals launch successfully using that bundled helper, including when the C# AppHost's application directory is outside the bundle.
- A missing explicitly selected bundled helper produces a clear failure rather than falling back to another executable.
- Packaging/discovery coverage protects the helper's presence, target architecture, and explicit path selection. Unix native-asset behavior remains unchanged.

### Additional context

This is an **Aspire build/signing/distribution change**, not a request to sign binaries in Hex1b's upstream build pipeline or republish its NuGet package.

The currently pinned Hex1b version already provides loose Windows native assets and the `WindowsPtyHostPath` override; no upstream runtime API change is required. Truly standalone, non-bundle consumers continue to use their normal Hex1b assets unless separately configured.

Related: #19887 (AppHost-owned terminals), #19554 (previously excluding the unused helper).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.