Skip to content
fabricators docs
On this page

Adapt existing API and worker hosts

Make relay trust, template encoding, timing disclosure and product migration explicit.

Status: released in Foundation 0.13.0. No consumer application code or database is changed by installing these packages.

Existing encrypted records belong to the consumer

Foundation does not add legacy cryptographic profiles or try a second purpose chain after decryption fails. A product migrating existing records owns the old reader, record-format discriminator, migration transaction, progress, retries and rollback plan. It must keep old key-ring entries and wrapping certificates until all dependent records have migrated.

The application keeps its existing OAuth protector during that transition, explicitly decrypts the old payload and protects it with the new Foundation scope. Do not replace the reader before the records can be read in the new format. Do not use a catch-all decryption fallback to classify records.

The key-ring storage adapter itself uses Microsoft's standard format. Preserve the existing key table, application discriminator and required certificates when adopting it. That preserves existing protectors; it does not make two different purpose chains compatible. Existing cookies retain their own purposes. See secret protection for storage and certificate rules.

An environment named Development does not alone permit plaintext key persistence. AllowUnencryptedKeysInDevelopment is also required and defaults to false. Shared development stacks that require encrypted keys must leave it false and supply their certificate, even when ASP.NET reports Development.

Explicit plaintext SMTP relay

SmtpSecurity.StartTls remains the default and requires TLS; Tls requires implicit TLS. Neither falls back to cleartext. UnencryptedLoopback continues to accept only a literal loopback IP.

For an explicitly authorized plaintext relay, including Docker DNS names:

csharp
var options = new SmtpOptions
{
    Host = "smtp",
    Port = 25,
    Security = SmtpSecurity.UnencryptedTrustedRelay
};

This mode deliberately sends without TLS. Anonymous relay access needs no further switch. Passwords and OAuth tokens are rejected by default on both plaintext modes, including loopback, before credential transmission. Connected OAuth also rejects the profile before acquiring a token. Sending credentials without TLS requires the separate trusted-host setting AllowCredentialsOverUnencryptedConnection = true. Choosing a plaintext transport or relaxing certificate validation does not implicitly grant that permission. TLS modes do not need this exception.

The transport does not infer network trust from DNS or a private address and does not add opportunistic downgrade behavior. The product owns relay selection and network policy; never bind raw SMTP settings from an unauthenticated request. Certificate-validation policies only affect modes that actually use TLS.

Both standalone and connected SMTP submission classify transport failures with MailSubmissionException and no raw MailKit inner exception/reply. Authentication failures are AuthenticationRequired; explicit permanent rejection is Rejected; a dropped connection after submission begins is UnknownOutcome, not a safe retry. Connection probes continue to avoid MAIL/RCPT/DATA entirely.

Templates that already escape their values

The existing TemplateOutputKind.Html still encodes input strings automatically. Changing that default would silently expose templates that rely on it. For a trusted template whose author already controls escaping, explicitly choose:

csharp
string body = await renderer.RenderAsync(
    "<p>{{ name | html.escape }}</p>",
    data,
    TemplateOutputKind.HtmlExplicitEscaping,
    cancellationToken);

This mode passes raw values into the template and exposes html.escape using HtmlEncoder.Default, preserving template-controlled escaping without doubling it. Every untrusted HTML insertion must be escaped by the template; raw insertion is intentionally raw. HTML escaping is not URL validation or JavaScript escaping. Only trusted template authors may select this mode. Text output is unchanged. Do not neutralize html.escape globally. The parse cache is shared syntax only; rendering data, functions and encoding mode remain isolated per rendering call.

The product chooses this mode per migrated template or migrates its templates to automatic encoding. Foundation does not edit stored templates or choose by looking for html.escape in the source.

Named timing phases and existing developer panels

Place diagnostics outside the phases to be measured. Checkpoints measure the forward pipeline from the previous checkpoint; the first starts at diagnostics entry. The endpoint measurement is the time since the last checkpoint until response start:

csharp
app.UseFabricatorsRequestDiagnostics(options =>
{
    options.DisclosurePolicy = "diagnostics.read";
    options.ExposeInDevelopment = false;
});
app.UseAuthentication();
app.UseAuthorization();
app.StampFoundationTimingPhase("auth");
// Resolve the authorized product scope here.
app.StampFoundationTimingPhase("scope");

RequestMeasurements.Current also offers MeasurePhase(name) and RecordPhase(name, duration) for bounded domain work. Names are trusted static identifiers: lowercase ASCII letters, digits, dash and underscore, starting with a letter, at most 32 characters and 32 distinct names per request. Standard names backend/total/endpoint/db/cache are reserved. Concurrent repeated phase measurements accumulate count and duration without crossing request scopes.

Total, endpoint and named-phase values are frozen together from one monotonic timestamp at response start, before any asynchronous disclosure-policy check. The JSON adapter receives that same snapshot; disclosure work does not inflate endpoint while leaving total frozen at an earlier instant.

Server-Timing includes backend, its total alias, endpoint, named phases and database/cache aggregates. Database, cache and manual scopes may overlap other phases; summing them is not the wall-clock duration. Measurements end at response start, not at the end of a streaming response or at browser page completion.

An optional RequestDiagnosticsOptions.JsonHeaderName emits a JSON report behind the same disclosure check. A consumer may set JsonPayloadFactory to adapt the report to an existing frontend's field names, such as an existing x-ic-timing contract. Foundation has no IC-specific header or payload. Header names must be X-prefixed ASCII tokens; a JSON payload larger than 8192 characters is omitted. The callback runs only after disclosure is authorized. Do not include secrets, identifiers or raw request paths in that callback.

Production disclosure still requires an authorization policy. It was already supported in 0.12.0. Development was the default convenience in 0.13.0; the 0.14.0 release disables it by default. Prefer the public permission/environment gate for new hosts. BFF forwarding and any cross-origin header exposure remain consumer decisions.

OpenAPI paths and consumer filters

csharp
services.AddFoundationOpenApi("Product API", configure: swagger =>
    swagger.OperationFilter<ProductGatingFilter>());
app.MapFoundationOpenApi(options =>
{
    options.DocumentRoutePattern = "/swagger/{documentName}/swagger.json";
    options.UiRoutePrefix = "/reference";
    options.AuthorizationPolicy = "docs.read";
});

Scalar uses the same configured document route. The document and UI entry points both require a configured policy, including in Development when supplied. Without a policy, production mapping remains disabled. Defaults remain /openapi/{documentName}.json and /scalar for existing consumers. Pass filter registration through the SwaggerGen callback; the product owns its endpoint security metadata and filter implementations. IC must adapt its filters to the selected Swashbuckle 11 API in IC. Foundation does not import them.

Logging in APIs and classic workers

AddFoundationObservability supports both IHostApplicationBuilder and classic IHostBuilder. Existing AddFabricatorsObservability calls remain supported. The selected baseline already includes Serilog.Extensions.Hosting 10 and OpenTelemetry 1.21; no additional dependency downgrade is needed.

csharp
new HostBuilder().AddFoundationObservability(
    (context, options) =>
    {
        options.ServiceName = "product-worker";
        options.EnableConsoleSink = false;
    },
    (context, logger) => logger.ReadFrom.Configuration(context.Configuration));

The default compact JSON console sink is enabled unless explicitly disabled. Disable it when the product config already declares its console sink. Configure that logger through Foundation's callback instead of separately registering a second Serilog provider. Trace correlation and sensitive framework-log filtering remain applied to both host styles; optional OTLP configuration uses the same service metadata and provider registration.

Evidence and remaining adoption work

The verification suite exercises hostname-based SMTP against a real local relay, raw SMTP failure redaction, explicit/default template encoding, protected custom OpenAPI endpoints, consumer operation filters, named timing and JSON disclosure, classic/modern worker hosts and an independently packaged host with exactly one console emission. Private relay DNS/network routing and IC's record/template migrations are consumer rollout work, not claimed as deployed by these tests.

↑ ↓ to move↵ to openSearching fabricators .NET foundation v0.19.0