mxaccessgw/docs/plans/2026-06-01-gateway-cert-autogen-design.md

# Gateway TLS Auto-Certificate and Lenient Client Trust — Design

Date: 2026-06-01
Status: Approved (brainstorming), pending implementation plan

## Problem

The gateway can serve gRPC and the dashboard over TLS, but only if an operator
supplies a certificate via the Kestrel `https://` endpoint config. With no cert,
an `https` endpoint fails at startup with Kestrel's opaque "No server certificate
was specified" error. Both current deployments therefore run plaintext (`h2c`),
exposing the API key and request payloads on the wire.

`mxaccessgw` is an internal tool. The goal is for TLS to "just work" with zero PKI
management: the gateway fabricates its own long-lived certificate when an HTTPS
endpoint is configured without one, and clients accept whatever certificate is
presented unless an operator explicitly opts into pinning.

## Decisions

1. **Gateway = fill-missing-cert-only.** No new "enable TLS" switch. TLS is still
   driven by configuring a Kestrel `https://` endpoint. New behavior: when an
   HTTPS endpoint has no `Certificate` section, the gateway generates/loads a
   persisted self-signed cert instead of failing. Plaintext-only hosts are
   untouched — no certificate or key material is ever written for them.
2. **Persist & reuse.** The self-signed cert is saved as a PFX under
   `C:\ProgramData\MxGateway\certs`, reused across restarts, regenerated only if
   missing, expired, or unreadable. Stable thumbprint; survives restarts; any
   CA-pinning client keeps working.
3. **Clients = lenient TLS, plaintext default.** When a client connects over TLS
   without a pinned CA, it skips verification (accepts any cert). Pinning a CA file
   restores full verification. The per-client connection default (mostly
   plaintext/`http`) does not change — TLS is still opt-in via the endpoint scheme.

**Scope boundary:** the gateway↔worker named-pipe IPC is unchanged (local,
OS-secured by the pipe ACL). This work touches only the public gRPC/dashboard
transport and the five language clients.

## Gateway component

New type `SelfSignedCertificateProvider` in
`src/ZB.MOM.WW.MxGateway.Server/Security/Tls/`.

1. **Detect need.** Inspect `Kestrel:Endpoints:*` configuration at startup. If any
   endpoint has an `https://` URL and no `Certificate` subsection, a default cert
   is needed. If none do, the provider is a no-op (no file written).
2. **Load-or-create.** Look for the persisted PFX. If present, valid, and
   unexpired, load it. Otherwise generate and persist.
3. **Generate.** `CertificateRequest` with **ECDSA P-256**, `notBefore = now - 1
   day` (clock-skew slack), `notAfter = now + ValidityYears`. SANs: `DNS=localhost`,
   `DNS=<MachineName>`, `DNS=<MachineName.FQDN>` when resolvable, plus
   `IP=127.0.0.1` and `IP=::1`. Server-auth EKU.
4. **Persist securely.** Write the PFX with an **empty** export password (a random
   in-memory password cannot be reused across restarts, which the persist-and-reuse
   decision requires); protect the private key with a restrictive ACL (SYSTEM +
   Administrators + service account) on the `certs` directory and file on Windows,
   and `0600` on non-Windows; atomic write (temp + rename). After generating, the
   cert is reloaded from the persisted PFX so Kestrel always serves the on-disk key.
5. **Wire into Kestrel.** In `GatewayApplication.CreateBuilder`, add
   `builder.WebHost.ConfigureKestrel(o => o.ConfigureHttpsDefaults(h =>
   h.ServerCertificate = cert))`. `ConfigureHttpsDefaults` supplies the cert only
   for HTTPS endpoints that did not specify their own, so an operator-configured
   `Kestrel:Endpoints:*:Certificate` transparently overrides it. One hook covers
   both the gRPC and dashboard ports.

### New config block `MxGateway:Tls`

All optional; the zero-config path needs none of them.

| Option | Default | Purpose |
|---|---|---|
| `Tls:SelfSignedCertPath` | `C:\ProgramData\MxGateway\certs\gateway-selfsigned.pfx` | Where the generated cert lives |
| `Tls:ValidityYears` | `10` | Lifetime of the generated cert |
| `Tls:AdditionalDnsNames` | `[]` | Extra SANs (e.g. a load-balancer name) |
| `Tls:RegenerateIfExpired` | `true` | Auto-replace an expired persisted cert |

Validated by `GatewayOptionsValidator`: `ValidityYears` in 1–100,
`SelfSignedCertPath` is a valid path shape when non-blank, and
`AdditionalDnsNames` entries are non-blank. (The "https endpoint exists but cert
path is blank" fail-fast lives in the bootstrap/provider, not the validator,
because the validator only sees the `MxGateway` section, not `Kestrel:Endpoints`.)

**Logging:** on generate/load, log thumbprint + SAN list + `notAfter` at
Information. Never log the PFX password or private key.

## Client lenient-TLS behavior

Uniform rule: **TLS on + no CA pinned ⇒ skip verification; CA pinned ⇒ full
verification.** No transport default changes. Each client also exposes an explicit
switch to force-disable leniency (strict-without-pinning) for the future.

| Client | Mechanism | Effort |
|---|---|---|
| .NET | In `CreateHttpHandler`, when `UseTls` and `CaCertificatePath` empty, set `SslOptions.RemoteCertificateValidationCallback = (_,_,_,_) => true`. CA path keeps existing custom-root validation. | trivial |
| Go | In `buildCredentials`, when TLS and no `CACertFile`/`TLSConfig`, use `tls.Config{InsecureSkipVerify: true, ServerName: override}`. | trivial |
| Java | grpc-netty-shaded 1.76.0 ships `InsecureTrustManagerFactory`. When TLS and no CA, build `GrpcSslContexts.forClient().trustManager(InsecureTrustManagerFactory.INSTANCE)`. | easy |
| Python | grpc-python has no per-channel skip-verify. Fetch the server leaf cert at connect via `ssl.get_server_certificate((host, port))`, pass it as `root_certificates` to `ssl_channel_credentials`, plus `grpc.ssl_target_name_override`. Effectively trusts what is presented (TOFU). | moderate, special-cased |
| Rust | tonic 0.13.1 + rustls (`tls-ring`). Implement a custom `rustls::client::danger::ServerCertVerifier` that accepts everything, build a `rustls::ClientConfig` via `.dangerous().with_custom_certificate_verifier(...)`, feed it to the channel. May require a custom hyper-rustls connector if `ClientTlsConfig` will not take a raw rustls config. **Needs an API spike.** | highest |

### Honesty caveats

- **Python** is not literally "ignore the cert"; it pins whatever the server
  presents on first contact via a separate unverified TLS probe. For a self-signed
  internal cert this is the intended outcome. Documented as a difference.
- **Rust** leniency depends on the tonic 0.13 TLS surface. If a custom verifier is
  disproportionately invasive, the fallback is to require a CA file for Rust TLS
  (pin-only) and document Rust as the exception.

## Error handling

Gateway:
- Cert dir not writable / ACL fails ⇒ fail fast at startup with a diagnostic naming
  the path and required permission. No silent in-memory fallback.
- Persisted PFX corrupt/unreadable ⇒ warn, regenerate, overwrite.
- Persisted cert expired ⇒ regenerate if `RegenerateIfExpired` (default), else fail
  fast instructing the operator to delete it or enable regeneration.
- HTTPS endpoint configured but generation disabled / path empty ⇒ validator
  rejects at startup rather than letting Kestrel throw its opaque error.

Clients: surface unchanged. Skip-verify cannot itself raise. Python's pre-fetch
wraps connect failure into the existing connect-error type with the endpoint in the
message. Rust pin-only fallback surfaces the existing CA-file error.

## Documentation (same commit as source, per CLAUDE.md)

- `docs/GatewayConfiguration.md` — extend the TLS section: auto-generation, the
  `MxGateway:Tls:*` block, persistence location/ACL, thumbprint logging, operator
  override via `Kestrel:Endpoints:*:Certificate`.
- Each client README + `*ClientDesign.md` — "TLS is lenient by default; pin a CA to
  verify," with Python TOFU and any Rust caveat noted.
- `docs/DesignDecisions.md` — record both posture choices and the why (internal
  tool, no PKI) so they are not mistaken for an oversight.

## Testing

Gateway (`MxGateway.Tests`, no MXAccess):
- `SelfSignedCertificateProvider`: SANs, server-auth EKU, `notAfter ≈ now +
  ValidityYears`, ECDSA P-256.
- Load-or-create: valid persisted PFX reused (same thumbprint); expired regenerates
  when enabled; corrupt regenerates with a warning.
- Detection: HTTPS-without-cert engages; all-plaintext no-ops and writes no file;
  endpoint with its own cert is not overridden.
- `GatewayOptionsValidator`: new `Tls:*` rules.
- Host integration: `Kestrel:Endpoints:Http:Url=https://127.0.0.1:0` builds and
  binds (today it throws "no certificate specified").

Clients: each test project gets a lenient-TLS test against a throwaway self-signed
cert — connect with no CA succeeds; pinning a wrong CA fails (proves pinning still
verifies). Python exercises the pre-fetch path; mark opt-in if loopback timing is
flaky. Standard (non-live) tests; no MXAccess or external services.

Cross-language: add a TLS variant note to `docs/CrossLanguageSmokeMatrix.md`;
running the matrix over TLS stays manual/opt-in, consistent with the existing gate.

Per-component verification follows CLAUDE.md's source-update table (build + test
each touched component independently).