Rework certificate environment and argument config to be more idiomatic

src/Aspire.Hosting.NodeJs/NodeExtensions.cs

@@ -83,16 +83,15 @@ public static IResourceBuilder<NodeAppResource> AddNpmApp(this IDistributedAppli
     private static IResourceBuilder<TResource> WithNodeDefaults<TResource>(this IResourceBuilder<TResource> builder) where TResource : NodeAppResource =>
         builder.WithOtlpExporter()
             .WithEnvironment("NODE_ENV", builder.ApplicationBuilder.Environment.IsDevelopment() ? "development" : "production")
-            .WithExecutableCertificateTrustCallback((ctx) =>
+            .WithCertificateTrustConfiguration((ctx) =>
             {
                 if (ctx.Scope == CertificateTrustScope.Append)
                 {
-                    ctx.CertificateBundleEnvironment.Add("NODE_EXTRA_CA_CERTS");
+                    ctx.EnvironmentVariables["NODE_EXTRA_CA_CERTS"] = ctx.CertificateBundlePath;
                 }
                 else
                 {
-                    ctx.CertificateTrustArguments.Add("--use-openssl-ca");
-                    ctx.CertificateBundleEnvironment.Add("SSL_CERT_FILE");
+                    ctx.Arguments.Add("--use-openssl-ca");
                 }
 
                 return Task.CompletedTask;
@@ -318,7 +317,7 @@ private static IResourceBuilder<TResource> AddNpmPackageManagerAnnotation<TResou
             foreach (var line in lines)
             {
                 var trimmedLine = line.Trim();
-                if (trimmedLine.StartsWith("nodejs ", StringComparison.Ordinal) || 
+                if (trimmedLine.StartsWith("nodejs ", StringComparison.Ordinal) ||
                     trimmedLine.StartsWith("node ", StringComparison.Ordinal))
                 {
                     var parts = trimmedLine.Split(' ', StringSplitOptions.RemoveEmptyEntries);

src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs

@@ -330,7 +330,7 @@ private static IResourceBuilder<PythonAppResource> AddPythonAppCore(
         // way to simply append additional certificates to default Python trust stores such as certifi.
         resourceBuilder
             .WithCertificateTrustScope(CertificateTrustScope.System)
-            .WithExecutableCertificateTrustCallback(ctx =>
+            .WithCertificateTrustConfiguration(ctx =>
             {
                 if (ctx.Scope == CertificateTrustScope.Append)
                 {
@@ -342,21 +342,16 @@ private static IResourceBuilder<PythonAppResource> AddPythonAppCore(
                 {
                     // Override default certificates path for the requests module.
                     // See: https://docs.python-requests.org/en/latest/user/advanced/#ssl-cert-verification
-                    ctx.CertificateBundleEnvironment.Add("REQUESTS_CA_BUNDLE");
+                    ctx.EnvironmentVariables["REQUESTS_CA_BUNDLE"] = ctx.CertificateBundlePath;
 
                     // Requests also supports CURL_CA_BUNDLE as an alternative config (lower priority than REQUESTS_CA_BUNDLE).
                     // Setting it to be as complete as possible and avoid potential issues with conflicting configurations.
-                    ctx.CertificateBundleEnvironment.Add("CURL_CA_BUNDLE");
-
-                    // Override default certificates path for Python modules that honor OpenSSL style paths.
-                    // This has been tested with urllib, urllib3, httpx, and aiohttp.
-                    // See: https://docs.openssl.org/3.0/man3/SSL_CTX_load_verify_locations/#description
-                    ctx.CertificateBundleEnvironment.Add("SSL_CERT_FILE");
+                    ctx.EnvironmentVariables["CURL_CA_BUNDLE"] = ctx.CertificateBundlePath;
                 }
 
                 // Override default opentelemetry-python certificate bundle path
                 // See: https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html#module-opentelemetry.exporter.otlp
-                ctx.CertificateBundleEnvironment.Add("OTEL_EXPORTER_OTLP_CERTIFICATE");
+                ctx.EnvironmentVariables["OTEL_EXPORTER_OTLP_CERTIFICATE"] = ctx.CertificateBundlePath;
 
                 return Task.CompletedTask;
             });

src/Aspire.Hosting/ApplicationModel/CertificateTrustConfigurationCallbackAnnotation.cs

@@ -0,0 +1,115 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Aspire.Hosting.ApplicationModel;
+
+/// <summary>
+/// An annotation that indicates a resource wants to manage how custom certificate trust is configured.
+/// </summary>
+/// <param name="callback">The callback used to customize certificate trust for the resource.</param>
+public sealed class CertificateTrustConfigurationCallbackAnnotation(Func<CertificateTrustConfigurationCallbackAnnotationContext, Task> callback) : IResourceAnnotation
+{
+    /// <summary>
+    /// Gets the callback to invoke to populate or modify the certificate authority collection.
+    /// </summary>
+    public Func<CertificateTrustConfigurationCallbackAnnotationContext, Task> Callback { get; } = callback ?? throw new ArgumentNullException(nameof(callback));
+}
+
+/// <summary>
+/// Context provided to a <see cref="CertificateTrustConfigurationCallbackAnnotation"/> callback.
+/// </summary>
+public sealed class CertificateTrustConfigurationCallbackAnnotationContext
+{
+    /// <summary>
+    /// Gets the <see cref="DistributedApplicationExecutionContext"/> for this session.
+    /// </summary>
+    public required DistributedApplicationExecutionContext ExecutionContext { get; init; }
+
+    /// <summary>
+    /// Gets the resource to which the annotation is applied.
+    /// </summary>
+    public required IResource Resource { get; init; }
+
+    /// <summary>
+    /// Gets the command line arguments associated with the callback context. Values can be either a string or a path
+    /// value provider such as <see cref="CertificateBundlePath"/> or <see cref="CertificateDirectoriesPath"/>.
+    /// </summary>
+    /// <remarks>
+    /// <example>
+    /// <code language="csharp">
+    /// builder.AddContainer("my-resource", "my-image:latest")
+    ///    .WithCertificateTrustConfigurationCallback(ctx =>
+    ///    {
+    ///        ctx.Arguments.Add("--use-system-ca");
+    ///        return Task.CompletedTask;
+    ///    });
+    /// </code>
+    /// </example>
+    /// </remarks>
+    public required List<object> Arguments { get; init; }
+
+    /// <summary>
+    /// Gets the environment variables required to configure certificate trust for the resource.
+    /// The dictionary key is the environment variable name; the value can be either a string or a path
+    /// value provider such as <see cref="CertificateBundlePath"/> or <see cref="CertificateDirectoriesPath"/>.
+    /// By default the environment will always include an entry for `SSL_CERT_DIR` and may include `SSL_CERT_FILE` if
+    /// <see cref="CertificateTrustScope.Override"/> or <see cref="CertificateTrustScope.System"/> is configured.
+    /// </summary>
+    /// <remarks>
+    /// <example>
+    /// <code language="csharp">
+    /// builder.AddContainer("my-resource", "my-image:latest")
+    ///     .WithCertificateTrustConfigurationCallback(ctx =>
+    ///     {
+    ///         ctx.EnvironmentVariables["MY_CUSTOM_CERT_VAR"] = ctx.CertificateBundlePath;
+    ///         ctx.EnvironmentVariables["CERTS_DIR"] = ctx.CertificateDirectoriesPath;
+    ///         return Task.CompletedTask;
+    ///     });
+    /// </code>
+    /// </example>
+    /// </remarks>
+    public required Dictionary<string, object> EnvironmentVariables { get; init; }
+
+    /// <summary>
+    /// A value provider that will resolve to a path to a custom certificate bundle.
+    /// </summary>
+    public required ReferenceExpression CertificateBundlePath { get; init; }
+
+    /// <summary>
+    /// A value provider that will resolve to paths containing individual certificates.
+    /// </summary>
+    public required ReferenceExpression CertificateDirectoriesPath { get; init; }
+
+    /// <summary>
+    /// Gets the <see cref="CertificateTrustScope"/> for the resource.
+    /// </summary>
+    public required CertificateTrustScope Scope { get; init; }
+
+    /// <summary>
+    /// Gets the <see cref="CancellationToken"/> that can be used to cancel the operation.
+    /// </summary>
+    public required CancellationToken CancellationToken { get; init; }
+}
+
+internal sealed class CertificateTrustConfigurationPathsProvider
+{
+    /// <summary>
+    /// The actual path to the certificate bundle file to be resolved at runtime
+    /// </summary>
+    public string? CertificateBundlePath { get; set; }
+
+    /// <summary>
+    /// The actual path to the certificate directories to be resolved at runtime
+    /// </summary>
+    public string? CertificateDirectoriesPath { get; set; }
+
+    /// <summary>
+    /// Gets a reference expression that resolves to the certificate bundle path.
+    /// </summary>
+    public ReferenceExpression CertificateBundlePathReference => ReferenceExpression.Create($"{CertificateBundlePath}");
+
+    /// <summary>
+    /// Gets a reference expression that resolves to the certificate directories path.
+    /// </summary>
+    public ReferenceExpression CertificateDirectoriesPathReference => ReferenceExpression.Create($"{CertificateDirectoriesPath}");
+}

src/Aspire.Hosting/ApplicationModel/ContainerCertificatePathsAnnotation.cs

@@ -0,0 +1,63 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Immutable;
+
+namespace Aspire.Hosting.ApplicationModel;
+
+/// <summary>
+/// An annotation that allows overriding default certificate paths for container resources.
+/// </summary>
+public sealed class ContainerCertificatePathsAnnotation : IResourceAnnotation
+{
+    /// <summary>
+    /// The default destination path in the container under which custom certificates will be placed.
+    /// </summary>
+    public const string DefaultCustomCertificatesDestination = "/usr/lib/ssl/aspire";
+
+    /// <summary>
+    /// Default paths to default certificate bundle files in a container.
+    /// </summary>
+    public static ImmutableList<string> DefaultCertificateBundlePaths = ImmutableList.Create(
+        // Debian/Ubuntu/Gentoo etc.
+        "/etc/ssl/certs/ca-certificates.crt",
+        // Fedora/RHEL 6
+        "/etc/pki/tls/certs/ca-bundle.crt",
+        // OpenSUSE
+        "/etc/ssl/ca-bundle.pem",
+        // OpenELEC
+        "/etc/pki/tls/cacert.pem",
+        // CentOS/RHEL 7
+        "/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem",
+        // Alpine Linux
+        "/etc/ssl/cert.pem");
+
+    /// <summary>
+    /// Default paths to default directories containing individual CA certificates in a container.
+    /// </summary>
+    public static ImmutableList<string> DefaultCertificateDirectoriesPaths = ImmutableList.Create(
+        "/etc/ssl/certs",
+        "/usr/local/share/ca-certificates",
+        "/etc/pki/tls/certs");
+
+    /// <summary>
+    /// Paths to default certificate bundle files in the container that should be replaced when the resource's
+    /// <see cref="CertificateTrustScope"/> is set to <see cref="CertificateTrustScope.Override"/> or
+    /// <see cref="CertificateTrustScope.System"/>.
+    /// If not set, a set of common default paths for popular Linux distributions will be used.
+    /// </summary>
+    public List<string>? DefaultCertificateBundles { get; init; }
+
+    /// <summary>
+    /// Paths to default directories containing individual CA certificates in the container that should be appended
+    /// when the resource's <see cref="CertificateTrustScope"/> is set to <see cref="CertificateTrustScope.Append"/>.
+    /// If not set, a set of common default paths for popular Linux distributions will be used.
+    /// </summary>
+    public List<string>? DefaultCertificateDirectories { get; init; }
+
+    /// <summary>
+    /// The destination path in the container under which custom certificates will be placed.
+    /// If not set, defaults to /usr/lib/ssl/aspire.
+    /// </summary>
+    public string? CustomCertificatesDestination { get; init; }
+}