[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.

[David Pine (IEvangelist)]

🤖 Automated docs-accuracy review

Phase A source of truth: microsoft/aspire @ release/13.5 (SHA 8ab6999850d96e0023670799edbd4bdc245ad63c)
Claims extracted: 6 → ✅ 5 verified, 🟡 0 verified-with-nuance, ⚠️ 0 unverifiable, ❌ 0 contradicted, 📝 1 narrative
Phase B (doc-tester): served PR head 503ddd4d at http://localhost:4321/ · pages exercised: /app-host/typescript-apphost/, /app-host/certificate-configuration/ · 0 critical, 0 warnings

Verdict: ✅ APPROVE — the new subsection accurately describes behavior that is present on release/13.5, all links resolve, and the page renders cleanly.

ℹ️ Note: the source change (microsoft/aspire#15634) carries milestone 13.6, but the implementation is already present on release/13.5 (TypeScriptLanguageSupport.cs, GuestAppHostProject.ConfigureCertificateBundleEnvironmentAsync, CertificateService.ExportDevCertificatePem), so targeting release/13.5 is consistent with the code on that branch.

ℹ️ GitHub reported mergeable: unknown at review time (no confirmed conflict); this doesn't affect docs accuracy.

---

Phase A — Claim verification (microsoft/aspire@release/13.5)

No contradicted or unverifiable claims. Every behavioral and config claim matches the CLI certificate‑bundling implementation on the release branch. The only delta since the previously‑reviewed revision (48751f40) is accuracy‑neutral wording polish ("run time" → "runtime", spelling out "Developer Control Plane (DCP)", clarifying ASPIRE_HOME as the Aspire home directory).

✅ Verified claims (6) with evidence — expand to audit

Evidence paths are on microsoft/aspire@8ab6999850d96e0023670799edbd4bdc245ad63c.

#	Claim	Verdict	Evidence
D1	The CLI makes Node.js trust the same development certificate the DCP uses	verified	GuestAppHostProject.cs:610 ExportDevCertificatePem(...) → CertificateService.cs:208 exports the ASP.NET Core dev certificate public PEM (the cert DCP's HTTPS proxies use); method doc: "Configures a language runtime's certificate bundle to trust the ASP.NET Core development certificate."
D2	Exports the trusted dev cert into a content‑addressed PEM cache under ASPIRE_HOME	verified	CertificateService.cs:61 DevCertDirectory = AspireHomeDirectory/dev-certs; combined bundle written to AspireHome/dev-certs/<bundle-cache>/{prefix}-{XxHash128}.pem (GuestAppHostProject.cs:2058‑2067); ICertificateToolRunner.cs:36 "content‑addressed PEM file"
D3	Node.js is configured to trust the bundle via NODE_EXTRA_CA_CERTS	verified	TypeScriptLanguageSupport.cs:60 CertificateBundleEnvironmentVariable => "NODE_EXTRA_CA_CERTS"
D4	An existing NODE_EXTRA_CA_CERTS is preserved via a combined bundle rather than overwritten	verified	GuestAppHostProject.cs:2042‑2073 — reads existing value, builds [devCert, '\n', existing] combined bundle, caches by content hash, sets the var to the combined bundle; Windows env‑var casing handled (2047‑2049); behavior pinned by tests/Aspire.Cli.Tests/Projects/GuestAppHostProjectTests.cs:1300‑1385
D5	"See Certificate configuration" cross‑reference	verified	Target resolves HTTP 200 ("Certificate configuration | Aspire") — confirmed in Phase B
D6	Example: "connecting directly to the dashboard's OTLP endpoint from custom AppHost logic"	narrative	Illustrative example; not code‑verifiable, not blocking

---

Phase B — doc-tester results (blind user, live site only)

Focus area: new "Trusting the certificate for outbound TLS connections" subsection on the TypeScript AppHost page
Served: PR head 503ddd4d via pnpm dev at http://localhost:4321/
Tester: doc-tester agent — navigated the rendered site with browser automation; no microsoft/aspire source consulted in this phase.

Summary

Category	Passed	Failed	Warnings
Content Accuracy	2	0	0
Links	1	0	0
Navigation / Render	3	0	0

Critical Issues

None.

Warnings

None.

Passed Checks

• Page renders at /app-host/typescript-apphost/ (HTTP 200, title "TypeScript AppHost project structure | Aspire"); 0 console errors, 0 console warnings.
• New H3 "Trusting the certificate for outbound TLS connections" renders under the existing "HTTPS development certificates" section and appears in the on‑this‑page TOC (anchor #trusting-the-certificate-for-outbound-tls-connections).
• Both explanatory paragraphs render with correct inline code for ASPIRE_HOME and NODE_EXTRA_CA_CERTS.
• The "Certificate configuration" link (/app-host/certificate-configuration/) resolves to a valid, on‑topic page ("Certificate configuration | Aspire").

Recommendations

1. No changes required — the subsection is accurate as rendered and its cross‑reference resolves.

Knowledge gap

None identified. The section is self‑contained and the follow‑up link points at the right place for deeper certificate‑management details.

---

_{Reviewed revision 503ddd4d4e98bee145566828748c40366568332e. Phase A read only from microsoft/aspire@release/13.5; Phase B consulted only the locally‑served, rendered docs site.}