[docs] Document TypeScript AppHost dev-cert trust for outbound TLS connections

[aspire-repo-bot]

Documents changes from microsoft/aspire#15634

@danegsta

Targeting release/13.5 — the latest release branch on microsoft/aspire.dev — because release/13.6 (from the source PR milestone 13.6) does not exist there.

Why this PR is needed

The source PR (polyglot_code_generator_changed signal triggered on TypeScriptLanguageSupport.cs) ensures TypeScript AppHosts trust the ASP.NET Core development certificate when custom AppHost code opens TLS connections to Aspire-managed resources in run mode. Specifically it:

• Exports the trusted development certificate selected by DCP into a content-addressed PEM cache under ASPIRE_HOME.
• Declares the runtime-specific certificate bundle environment variable through TypeScript language support metadata (NODE_EXTRA_CA_CERTS).
• Preserves an existing NODE_EXTRA_CA_CERTS value by creating a secure, content-addressed combined bundle.
• Handles Windows environment-variable casing without allowing duplicate aliases to override the generated bundle.

This is user-facing behavior for anyone running a TypeScript AppHost that makes outbound HTTPS connections (e.g., to the dashboard's OTLP endpoint), and it wasn't previously documented on the TypeScript AppHost page.

What changed

Added a new subsection, "Trusting the certificate for outbound TLS connections", under the existing "HTTPS development certificates" section of app-host/typescript-apphost.mdx, explaining:

• The CLI automatically trusts the dev cert for outbound TLS from Node.js via a content-addressed PEM cache under ASPIRE_HOME.
• How NODE_EXTRA_CA_CERTS is used and how existing values are preserved via a combined bundle.
• A cross-reference to the existing Certificate configuration page.

Files modified

• src/frontend/src/content/docs/app-host/typescript-apphost.mdx (updated)

No new pages were created; this extends existing documentation.

Generated by PR Documentation Check for #15634 · auto · 55 AIC · ⌖ 5.96 AIC · ⊞ 19.6K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1493. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[Copilot]

Pull request overview

Adds missing documentation to the TypeScript AppHost guide explaining how the Aspire CLI ensures outbound TLS from Node.js trusts the same development certificate used by Aspire orchestration, including how NODE_EXTRA_CA_CERTS is set/combined.

Changes:

• Added a new “Trusting the certificate for outbound TLS connections” subsection under “HTTPS development certificates”.
• Documented the ASPIRE_HOME PEM cache behavior and NODE_EXTRA_CA_CERTS handling (including preserving existing values).
• Added/retained a cross-reference to Certificate configuration docs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[David Pine (IEvangelist)]

Automated docs-accuracy review — Phase A (claims) + Phase B (doc-tester)

Phase A source of truth: microsoft/aspire @ release/13.5, SHA 8ab6999850d96e0023670799edbd4bdc245ad63c (matches this PR's base).
Reviewed head SHA: 48751f40cf958e938ce6f4f57659796883cf0c26.

Phase A — claims: 4 non-narrative claims extracted → 4 verified, 0 verified-with-nuance, 0 unverifiable, 0 contradicted.
Phase B — doc-tester: 1 page exercised (/app-host/typescript-apphost/, anchor #trusting-the-certificate-for-outbound-tls-connections) → 0 critical, 0 warnings, 0 knowledge gaps.

Verdict: APPROVE — every factual claim in the new "Trusting the certificate for outbound TLS connections" section matches the CLI's GuestAppHostProject certificate-bundle logic on release/13.5, and the section renders cleanly.

---

Phase A — Claim verification

No contradicted or unverifiable claims. The feature is present on the targeted release/13.5 branch and the prose matches the implementation precisely.

Verified claims (4) with source evidence

Evidence paths are in microsoft/aspire @ release/13.5 (8ab6999).

• The CLI exports the trusted dev certificate and configures Node.js to trust it — verified. src/Aspire.Cli/Projects/GuestAppHostProject.cs:608-614 — when the guest runtime declares a CertificateBundleEnvironmentVariable, the CLI calls _certificateService.ExportDevCertificatePem(...) then ConfigureCertificateBundleEnvironmentAsync(...). src/Aspire.Cli/Certificates/NativeCertificateToolRunner.cs:199-236 selects the trusted ASP.NET Core HTTPS development certificate and exports its public PEM (the shared dev cert).
• Exported into a content-addressed PEM cache under ASPIRE_HOME — verified. src/Aspire.Cli/Certificates/CertificateService.cs:60-61 — DevCertDirectory => Path.Combine(executionContext.AspireHomeDirectory.FullName, "dev-certs"). NativeCertificateToolRunner.GetOrCreateCertificateCacheFile(...) writes aspire-dev-cert-{hash}.pem where hash = XxHash128.Hash(pemContents) (content-addressed), via CertificateCacheWriter.WriteFile (CertificateCacheWriter.cs:52: "Another process published the same content-addressed file first").
• Node.js is configured through the NODE_EXTRA_CA_CERTS environment variable — verified. src/Aspire.Hosting.CodeGeneration.TypeScript/TypeScriptLanguageSupport.cs:60 — CertificateBundleEnvironmentVariable => "NODE_EXTRA_CA_CERTS"; GuestAppHostProject.cs:2085 — SetCertificateBundleEnvironmentVariable(..., environmentVariableName /* NODE_EXTRA_CA_CERTS */, certificateBundlePath).
• An existing NODE_EXTRA_CA_CERTS value is preserved via a combined bundle containing both certificates, not overwritten — verified. GuestAppHostProject.cs ConfigureCertificateBundleEnvironmentAsync (lines ~2037-2085): reads existingCertificateBundle; if set and different, builds bundleContents = [.. devCertificateContents, (byte)'\n', .. existingBundleContents] (both included, Aspire cert first), writes a content-addressed {cacheFilePrefix}-{bundleHash}.pem under AspireHomeDirectory/dev-certs/bundles, and on I/O failure falls back to the existing bundle unchanged. Covered by tests/Aspire.Cli.Tests/Projects/GuestAppHostProjectTests.cs.

The illustrative example ("connecting directly to the dashboard's OTLP endpoint from custom AppHost logic") is narrative framing and was not treated as a hard claim.

---

Phase B — Doc-tester results

Report reproduced verbatim from the doc-tester skill run (blind to source; navigation via Playwright; served locally with pnpm dev).

Documentation Test Report

Focus Area: PR #1493 TypeScript AppHost outbound TLS certificate trust subsection
Date: 2026-08-14
Tester: doc-tester agent
Served Base URL: http://localhost:4321/
Served Head SHA: 48751f40cf958e938ce6f4f57659796883cf0c26

Routes Exercised:

• http://localhost:4321/app-host/typescript-apphost/
• http://localhost:4321/app-host/typescript-apphost/#trusting-the-certificate-for-outbound-tls-connections

Screenshots:

• pr1493-trusting-certificate-outbound-tls.png

Summary

Category	Passed	Failed	Warnings
Content Accuracy	4	0	0
Code Examples	0	0	0
CLI Commands	0	0	0
Links	2	0	0

Critical Issues

None.

Warnings

None.

Passed Checks

• The TypeScript AppHost page loaded successfully.
• The "Trusting the certificate for outbound TLS connections" subsection appears in the "On this page" navigation.
• Clicking the navigation entry resolved to #trusting-the-certificate-for-outbound-tls-connections.
• Both new paragraphs rendered cleanly.
• ASPIRE_HOME rendered with inline code formatting.
• NODE_EXTRA_CA_CERTS rendered with inline code formatting in both paragraphs.
• The text clearly explains that Aspire preserves an existing NODE_EXTRA_CA_CERTS value by generating a combined bundle.
• The following "Certificate configuration" LearnMore link still rendered.
• The "Certificate configuration" link points to /app-host/certificate-configuration/ with a trailing slash.
• No broken anchor, duplicated content, or formatting issue was observed in the tested section.

Recommendations

1. Priority fixes: None.
2. Documentation gaps: None found in the tested section.
3. Product issues: None discovered from blind documentation testing.

Knowledge Gaps

None.

---

Automated review: Phase A verifies claims against microsoft/aspire source at the release-branch SHA; Phase B validates the rendered docs as a new user via the doc-tester skill.