# Protect persisted secrets and verify SMTP connections

Share an encrypted key ring and resolve mailbox settings at runtime without restarting.

Status: **released in Foundation 0.13.0**.
No mailbox store, tenant permissions or application frontend is supplied here.

## Responsibilities

| Foundation | Consuming product |
| --- | --- |
| `ISecretProtector`, stable purpose hierarchy and size bounds | Authorized scope identifiers and the secret records |
| `AddFoundationDataProtection` and certificate configuration | Certificate acquisition, lifetime, permissions and retention |
| `AddFoundationDataProtectionEf<TContext>` | Stable key-ring context, provider, mapping, migrations and backup |
| Connection verification and SMTP protocol/TLS/authentication | Current mailbox ownership, grants and settings resolution |
| Stable redacted transport failures | Authorized UI actions, audit and user-facing messages |

`Fabricators.Application` contains the provider-neutral secret/verification ports.
`Fabricators.Security.DataProtection` implements protection without EF or an HTTP
host. Its optional `.EntityFrameworkCore` adapter uses Microsoft's key-ring
repository against a host-owned `DbContext` implementing `IDataProtectionKeyContext`.
The two Microsoft packages are pinned to the selected .NET/EF 10 patch line.

## Register a persistent key ring

```csharp
using Fabricators.Security.DataProtection.EntityFrameworkCore;

services.AddDbContext<ProductKeyRingContext>(options =>
    options.UseNpgsql(connectionStringFromSecureConfiguration));
services.AddFoundationDataProtectionEf<ProductKeyRingContext>(
    environment,
    options =>
    {
        options.ApplicationName = "product-cloud";
        options.KeyEncryptionCertificate = loadedCertificate;
        options.DecryptionCertificates = retainedCertificates;
    });
```

The context exposes `DbSet<DataProtectionKey> DataProtectionKeys`. Generate and
apply its mapping/migration through the product's normal deployment mechanism.
The library does not create tables, run migrations or change product histories.
Use a stable platform key-ring database, not a context whose database selection
depends on the current request's tenant. API and worker replicas that need to
decrypt the same secrets use the same application name, storage and certificates.

`AddFoundationDataProtection` returns `IDataProtectionBuilder` for other explicit
repositories such as `PersistKeysToFileSystem`. Missing explicit persistence or
a conflicting application-name override fails options validation. A certificate
with a private RSA key of at least 2048 bits is required by default. The host owns
its lifetime and must retain it while the provider needs it.

Only Development may opt into `AllowUnencryptedKeysInDevelopment`; the default
remains false there too. Production, Staging and unknown environments cannot use
that opt-in to bypass certificate requirements. Removing key encryption after
registration also fails validation. Certificate protection prevents a database
read from exposing the raw master keys; the key-ring store still needs restricted
write access. It is not protection against arbitrary database modification.

These defaults follow the [working Microsoft EF repository](https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/implementation/key-storage-providers?view=aspnetcore-10.0#entity-framework-core)
and its [certificate/key-retention configuration](https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview?view=aspnetcore-10.0).

## Protect records with explicit scope

```csharp
using Fabricators.Application.Security.Secrets;

var scope = new SecretProtectionScope("product-cloud",
    ["tenant", tenantId, "mailbox", connectionId, "smtp-password.v1"]);
string protectedValue = protector.Protect(scope, runtimePassword);
// Store protectedValue with the authorized connection record.
string runtimeValue = protector.Unprotect(scope, protectedValue);
```

Every segment is passed separately to Data Protection. Authority and purposes
are stable and case-sensitive, without normalization or flattened concatenation.
Use 1–16 purpose segments, each 1–200 characters, without control characters or
malformed Unicode. Authority follows the same segment bounds. Choose scopes from
trusted server context: knowing a scope or ciphertext is not an authorization grant.

Existing record-format and purpose-chain migrations are product-owned. Foundation
does not supply legacy profiles, autodetection or a second decryption fallback.
See [host compatibility](/foundation/0.19.0/guides/host-compatibility/) before replacing an existing reader.

Valid plaintext is preserved, including empty strings, Unicode and whitespace.
Bounds are 262144 UTF-16 code units for plaintext and 2097152 characters for
ciphertext. Oversize/malformed input fails; tampering, wrong scopes/application
names and missing keys never return plaintext or ciphertext as a fallback.
Protect OAuth refresh/access-token payloads through the same port with distinct
purposes. No secret values are logged or cached by this adapter.

For certificate rotation, use the new certificate for key encryption and retain
old private certificates in `DecryptionCertificates`. Existing keys remain stored
and Data Protection records their IDs in protected values. Keep those keys and
certificates for the required recovery period. This does not automatically
re-encrypt all historical rows or migrate an existing filesystem key ring into
the database. Preserve/import the existing ring and application name in a reviewed
product deployment before changing an already deployed storage backend.

## Verify and submit without restarting

```csharp
services.AddScoped<IMailConnectionAuthority, ProductMailAuthority>();
services.AddScoped<ISmtpConnectionSettingsSource, ProductSmtpSettings>();
services.AddFabricatorsConnectedSmtp();

MailConnectionVerification result = await verifier.VerifyAsync(connectionId, token);
await sender.SubmitAsync(connectionId, message, token);
```

`verifier` is `IConnectedMailConnectionVerifier`; `sender` is
`IConnectedMailTransport`. The product authority resolves the current connection
and requires `MailCapability.VerifyConnection` for verification. Send permission
alone does not grant verification. The SMTP adapter rechecks authority before
resolving settings/credentials and again after token acquisition, before network
I/O. Resolver arguments and previous successful probes do not grant access.

`ProductSmtpSettings` reads the authorized record and calls `ISecretProtector`
to return runtime-only `SmtpConnectionSettings`. Update its stored host, port,
credentials, TLS policy and connection revision normally; subsequent operations
resolve them again through the same services, without a restart. Revoke/rotate
the connection through the product authority. Do not cache admission or retain a
decrypted settings snapshot in a process singleton. Global `Host:Mail` startup
settings are not the SaaS tenant's mailbox-store model.

Verification connects, performs the selected TLS validation and authentication,
then disconnects. It never sends MAIL, RCPT or DATA. Anonymous, password and
connection-bound delegated/application OAuth profiles follow the same rules as
submission. `MailConnectionVerification` reports the connection/revision/provider
and completion time; it is not a delivery or send-as-permission guarantee.
Graph verification is not supplied by this increment.

The direct `SmtpMailTransport.VerifyConnectionAsync(token)` method also verifies
its supplied options without sending a message. High-level SaaS integrations
should use the connection-bound verifier so live grants/revisions are enforced.
Raw options and endpoint selection must come from an authorized server operation,
not an unauthenticated network-probe API.

`MailConnectionVerificationException` contains a stable `MailFailure`, with
no inner SMTP reply, password or token. Unsupported provider/unavailable selector
returns Unavailable; authentication failures return AuthenticationRequired.
Cancellation propagates. The existing submission ambiguity rules still apply
only after actual message submission starts. See [connected mail](/foundation/0.19.0/guides/connected-mail/)
for sender checks, submission acceptance and TLS policies.

Version 0.16.0 preserves `Diagnostics` through both submission and verification:
safe cause enums distinguish TLS, socket, protocol, authentication, configuration,
timeout and I/O; a socket error carries its numeric SocketError code. SMTP reply
status codes also survive verification. Log these structured properties when
operational context is needed. Raw MailKit messages/inner exceptions remain
excluded because providers may echo credentials or message data. UnknownOutcome
still means that automatic resubmission may duplicate an accepted message.

## Verification boundary

Tests use actual Data Protection and EF persistence with SQLite/PostgreSQL,
independent providers, encrypted stored XML, retained-certificate/key rotation,
scope/tamper/unknown-key rejection and concurrent PostgreSQL replicas. Real SMTP
and TLS fixtures check probes, rejected authentication, no message commands,
revocation during OAuth-token acquisition and encrypted database settings changed
between calls to the same verifier/sender. No external recipient or customer
mailbox is contacted; physical deployment/certificate provisioning stays product-owned.

Foundation CI/Publish caches restored NuGet dependencies by OS and lockfiles.
Independent package consumers retain isolated caches and restore our freshly
packed archives from a local feed; these checks do not pull Foundation archives
from GitHub Packages. Remote cache hits require a subsequent workflow run.
