# 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](/foundation/0.19.0/guides/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](/foundation/0.19.0/guides/authorization/) 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.
