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