SimulatedNetworkListenerOptions can now be supplied to ListenLocalAsync/ListenNetworkAsync to carry parameters, including a newly introduced way to carry a user-supplied certificate for encrypted connections and an IP address for binding.

Author: RyanLamansky

CLAUDE.md

@@ -123,7 +123,7 @@ Field rosters live in the source XML docs; this captures only identity + load-be
 
 - **`Simulation`** = server / instance.
   Holds `SystemHeapTables`, the `Databases` dict, and `ServerCollationName` (`init`-only; defaults `SQL_Latin1_General_CP1_CI_AS`; mirrors `model.collation` — install-time seed for every new `Database`, both the lazy `"simulated"` seed and collation-less bacpac imports; `init` reflects real immutability).
-  Public surface = `Simulation` ctor + `CreateDbConnection()` + `ImportBacpac()` + `AddRemoteSimulation()` + `ServerCollationName` + `ListenLocalAsync()` / `ListenNetworkAsync()` → `SimulatedNetworkListener`.
+  Public surface = `Simulation` ctor + `CreateDbConnection()` + `ImportBacpac()` + `AddRemoteSimulation()` + `ServerCollationName` + `ListenLocalAsync()` / `ListenNetworkAsync()` (int-port or `SimulatedNetworkListenerOptions` overloads) → `SimulatedNetworkListener`.
 - **`Database`** (internal) = one database.
   Holds `Schemas`, `CompatibilityLevel`, `CollationName`, the rowversion counter (`@@DBTS`), the MVCC version store, and the principal/permission/extended-property/full-text/DDL-trigger surfaces.
   `Databases` is seeded at construction with all four system databases — `master` / `tempdb` / `model` / `msdb` (so `USE <systemdb>` / `master.sys.*` / `master.dbo.<proc>` / SSMS's `msdb.dbo.syspolicy_system_health_state` all resolve without an import); the first `CreateDbConnection()` lazily seeds `DefaultDatabaseName` (`"simulated"`) when no *user* database is present, and all four system databases are excluded from the initial-database fallback (`Simulation.SystemDatabaseNames`) so a fresh connection still lands on `simulated`.
@@ -270,7 +270,7 @@ Each entry below is a trigger: read the linked file on demand when working in th
 - **New top-level statement parser or dispatch-loop separator rules, double-quoted identifiers / QUOTED_IDENTIFIER** → [`grammar.md`](docs/claude/grammar.md) + [`control-flow.md`](docs/claude/control-flow.md).
 - **BACPAC import** (`Simulation.ImportBacpac` — multi-database via repeated calls, `BacpacImportOptions`, `ModelXmlReader` dispatcher, BCP wire format, `BacpacBuilder` test harness) → [`bacpac-loader.md`](docs/claude/bacpac-loader.md).
 - **Linked servers** (`Simulation.AddRemoteSimulation`, `sp_addlinkedserver` / `sp_dropserver`, four-part FROM routing through the remote's ADO.NET pipeline, `OPENQUERY(server,'query')` ad-hoc pass-through + compile-time schema discovery, `sys.servers`) → [`linked-servers.md`](docs/claude/linked-servers.md).
-- **TDS network endpoint** (`Simulation.ListenLocalAsync` (loopback) / `Simulation.ListenNetworkAsync` (all interfaces, requires a registered login) → `SimulatedNetworkListener`; real SqlClient over loopback TCP+TLS; SQLBatch/RPC/TM/BulkLoad (`SqlBulkCopy`); legacy `text`/`ntext`/`image` result columns + `image` RPC input params in the in-band textptr wire form; TVP (`0xF3` `SqlDbType.Structured`) RPC params via the shared `TdsColumnDecoder`; `sp_cursor*` API-server-cursor RPC family; mid-stream attention (cancel / `CommandTimeout`) via a carry-forward concurrent read → `DONE_ATTN` ack + probed XACT_ABORT tx semantics; MARS (`MultipleActiveResultSets=True`) via an SMP demux/mux over one shared connection with serialized cooperative multiplexing + per-session attention; TDS 8.0 `Encrypt=Strict` (TLS-first, ALPN `tds/8.0`, client pins the exposed `SimulatedNetworkListener.ServerCertificate` since SqlClient ignores `TrustServerCertificate` in strict mode); credential enforcement via the `CREATE LOGIN` registry, Msg 18456 on mismatch; EF via plain `UseSqlServer`; oracles = `*.Tests.SqlClient` + `*.Tests.Smo`, the real-SMO consumer oracle) → [`tds-endpoint.md`](docs/claude/tds-endpoint.md).
+- **TDS network endpoint** (`Simulation.ListenLocalAsync` (loopback) / `Simulation.ListenNetworkAsync` (all interfaces, requires a registered login) → `SimulatedNetworkListener`, both with `SimulatedNetworkListenerOptions` overloads (port + caller-owned TLS certificate + network-only single-interface `BindAddress`); real SqlClient over loopback TCP+TLS; SQLBatch/RPC/TM/BulkLoad (`SqlBulkCopy`); legacy `text`/`ntext`/`image` result columns + `image` RPC input params in the in-band textptr wire form; TVP (`0xF3` `SqlDbType.Structured`) RPC params via the shared `TdsColumnDecoder`; `sp_cursor*` API-server-cursor RPC family; mid-stream attention (cancel / `CommandTimeout`) via a carry-forward concurrent read → `DONE_ATTN` ack + probed XACT_ABORT tx semantics; MARS (`MultipleActiveResultSets=True`) via an SMP demux/mux over one shared connection with serialized cooperative multiplexing + per-session attention; TDS 8.0 `Encrypt=Strict` (TLS-first, ALPN `tds/8.0`, client pins the exposed `SimulatedNetworkListener.ServerCertificate` since SqlClient ignores `TrustServerCertificate` in strict mode); credential enforcement via the `CREATE LOGIN` registry, Msg 18456 on mismatch; EF via plain `UseSqlServer`; oracles = `*.Tests.SqlClient` + `*.Tests.Smo`, the real-SMO consumer oracle) → [`tds-endpoint.md`](docs/claude/tds-endpoint.md).
 
 ## Not modeled
 

docs/claude/backlog.md

@@ -37,8 +37,7 @@ Remaining phases, roughly in value order:
   Candidate follow-on legs within tool scope: Visual Studio's SQL Server Object Explorer (DacFx-driven, a different query dialect from SMO) and LINQPad.
 - **SMO API sweep campaign** — `.vs/smo-sweep` (gitignored local harness) walks SMO's full reachable read surface against the self-hosted simulator and, identically, against the live reference, draining every `Property.Value` and `Script()`-ing every `IScriptable`; modes `sweep` / `sweep --live` / `diff` → sorted JSON reports + `reports/triage.md`; workflow = sweep both sides → triage → fix bundles → graduated `Tests.Smo` tests → re-sweep.
   Open items from the latest triage: (a) `DBCC SHOW_STATISTICS … WITH STATS_STREAM` (SMO `Statistic.Stream`) stays `NotSupportedException` — it wants the raw serialized statistics-histogram blob, which the simulator has no faithful source for; (b) the unmodeled runtime/OS surfaces SMO reaches as absent objects (backup history `msdb.dbo.backupset`, `sys.dm_tran_persistent_version_store_stats`, file-space/IO DMVs, `sys.dm_os_process_memory`, `master.dbo.sysprocesses`, `FILEPROPERTY`, registry/OS xps) — surfaced as `PropertyCannotBeRetrievedException` / defaults, the legitimate-gap category.
-- **Smaller fidelity items**: user-supplied `X509Certificate2` (a CA-trusted certificate instead of the ephemeral self-signed one; strict-mode clients can already pin the exposed `SimulatedNetworkListener.ServerCertificate`) and per-interface bind-address selection — add-on-demand public-surface expansions.
-  Open residuals of shipped wire features (details in [`tds-endpoint.md`](tds-endpoint.md)): cancel/attention reaction is bounded by the in-flight statement's materialization, not interruptible inside a single statement's row loop; MARS never raises Msg 8628/8651 and fully materializes each session's response under the execution gate.
+- **Open residuals of shipped wire features** (details in [`tds-endpoint.md`](tds-endpoint.md)): cancel/attention reaction is bounded by the in-flight statement's materialization, not interruptible inside a single statement's row loop; MARS never raises Msg 8628/8651 and fully materializes each session's response under the execution gate.
 - **Chunked `OFFSET/FETCH` paging: per-page constant factor, complexity class matches real** (probed 2026-07-18, plans + timings): real SQL Server also redoes the work on every page — `Top(OFFSET…)` over an ordered index scan reading offset+fetch rows when an index supplies the order, or a full scan + `Sort(TOP offset+fetch)` re-sorted per page when not; no cross-query sorted-result caching exists on either side, so "sort once, serve many pages" is rejected (it would invent behavior real doesn't have).
   The residual is constant-factor only: the simulator materializes (and for non-index order, sorts) all n rows per page regardless of offset where real's indexed plan touches only offset+fetch (measured at 150k rows / fetch 100 / offset 140k: sim ~41 ms vs real ~13 ms indexed, ~116 ms vs ~22 ms unindexed — real's sort is also 16-way parallel).
   Possible lever if paged drains ever matter: recognize index-supplied order in the `OFFSET/FETCH` path (real's plan shape) to skip the sort and bound the scan.

docs/claude/tds-endpoint.md

@@ -4,15 +4,18 @@
 Returns `Task<SimulatedNetworkListener>`; `port: 0` binds an OS-assigned ephemeral port (read `Port`), the right shape for parallel tests.
 Port-in-use surfaces as the raw `SocketException`.
 The listener binds IPv4 loopback plus best-effort IPv6 loopback on the same port.
+Both listen methods also take a **`SimulatedNetworkListenerOptions`** overload (`Port`, default 1433 matching the int overloads; `BindAddress`; `ServerCertificate`, default null = generate ephemeral): a supplied certificate must carry a private key (`ArgumentException` otherwise) and **stays owned by the caller — the listener never disposes it** — so one certificate serves many listeners (created once at suite setup, its public part exported once for strict-mode pinning instead of per-listener temp files).
+`BindAddress` narrows `ListenNetworkAsync` from all interfaces to exactly one address — its family decides the socket family and **no best-effort other-family sibling is bound** — while `ListenLocalAsync` rejects a non-null value with `ArgumentException` (honoring it would put the loopback method's accept-anyone-until-`CREATE LOGIN` credential model on a network interface).
 **`ListenNetworkAsync`** is the all-interfaces sibling (`IPAddress.Any` + best-effort `IPv6Any`, same core): it throws `InvalidOperationException` at call time when no logins are registered — the loopback listener's accept-anyone-until-`CREATE LOGIN` model must never face a network — and its XML docs carry the honest caveat that authentication is the *only* enforcement (no authorization model; every login has unrestricted access; the self-signed cert doesn't authenticate the server).
 Oracle: `NetworkListenerTests`.
 
-Connection-string requirements: `TrustServerCertificate=true` (the endpoint presents an ephemeral in-memory self-signed cert generated per listener) and credentials per the enforcement rule below (any credentials when no logins exist).
+Connection-string requirements: `TrustServerCertificate=true` (the endpoint presents an ephemeral in-memory self-signed cert generated per listener, unless the options overload supplied one — a CA-trusted supplied certificate makes the flag unnecessary) and credentials per the enforcement rule below (any credentials when no logins exist).
 Default/`Mandatory`/`Optional` all negotiate to full encryption via `ENCRYPT_REQ`.
 A client that cannot do TLS at all (`ENCRYPT_NOT_SUP`) is disconnected after the prelogin response — there is no plaintext mode.
 
 **`Encrypt=Strict` (TDS 8.0) ships**: the client opens with a bare TLS ClientHello negotiating ALPN `tds/8.0`, and every TDS packet — prelogin included — flows inside the TLS channel; the session routes on the first wire byte (TLS handshake record `0x16` vs cleartext PRELOGIN `0x12`).
 SqlClient **ignores `TrustServerCertificate` in strict mode** and always validates the certificate (chain + hostname), so a strict client must pin instead: export `SimulatedNetworkListener.ServerCertificate` (the presented certificate, public part only) to a file and reference it with the connection string's `ServerCertificate` keyword (empirically confirmed against SqlClient 7.0.2 — `TrustServerCertificate=True` alone fails strict with `UntrustedRoot` + hostname mismatch).
+Supplying one certificate through `SimulatedNetworkListenerOptions` makes the pin file a create-once artifact shared by every listener (the shape `StrictEncryptionTests` uses: one class-level certificate, its public part written to a fixed-name file in the OS temp directory).
 The strict TLS handshake is not version-pinned (TLS 1.3 negotiates; raw records make NewSessionTicket harmless), and LOGINACK echoes TDS version `0x08000000` when LOGIN7 requested it.
 MARS and `SqlBulkCopy` ride the strict channel unchanged.
 Oracle: `StrictEncryptionTests`.

src/SqlServerSimulator/Network/TdsServerCertificate.cs

@@ -10,7 +10,19 @@ namespace SqlServerSimulator.Network;
 /// </summary>
 internal static class TdsServerCertificate
 {
-    public static X509Certificate2 Create()
+    public static X509Certificate2 Create() =>
+        X509CertificateLoader.LoadPkcs12(CreatePkcs12(), password: null);
+
+    /// <summary>
+    /// PKCS#12 bytes (no password) for a fresh certificate. Exposed
+    /// separately from <see cref="Create"/> because the bytes must be
+    /// captured before <see cref="X509CertificateLoader"/> touches
+    /// a platform key store: Windows marks a loaded private key
+    /// non-exportable, so a store-loaded certificate cannot be re-exported
+    /// as PKCS#12 ("Key not valid for use in specified state") — callers
+    /// persisting the certificate write these bytes instead.
+    /// </summary>
+    public static byte[] CreatePkcs12()
     {
         using var rsa = RSA.Create(2048);
         var request = new CertificateRequest("CN=SqlServerSimulator", rsa, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
@@ -19,6 +31,6 @@ public static X509Certificate2 Create()
         // SslStream requires a certificate whose private key is loadable by
         // the platform TLS stack; round-tripping through PKCS#12 guarantees
         // that on every OS, where the CreateSelfSigned result alone does not.
-        return X509CertificateLoader.LoadPkcs12(selfSigned.Export(X509ContentType.Pkcs12), password: null);
+        return selfSigned.Export(X509ContentType.Pkcs12);
     }
 }

src/SqlServerSimulator/SimulatedNetworkListener.cs

@@ -8,11 +8,12 @@ namespace SqlServerSimulator;
 /// <summary>
 /// A TCP endpoint speaking the SQL Server wire protocol (TDS), letting
 /// unmodified SQL Server clients connect to a simulation with only a
-/// connection-string change. Created by the listen method on the simulation
-/// type; accepts loopback connections only. The endpoint presents an
-/// ephemeral self-signed TLS certificate, so clients must connect with
-/// <c>TrustServerCertificate=true</c>. Credentials are accepted without
-/// validation.
+/// connection-string change. Created by the listen methods on the simulation
+/// type; accepts loopback connections only. The endpoint presents the TLS
+/// certificate supplied through the listen options, or an ephemeral
+/// self-signed one when none was supplied — the latter requires clients to
+/// connect with <c>TrustServerCertificate=true</c>. Credentials are accepted
+/// without validation.
 /// </summary>
 /// <remarks>
 /// Disposal is immediate and waits for nothing: the listening sockets close,
@@ -39,24 +40,33 @@ public sealed class SimulatedNetworkListener : IDisposable, IAsyncDisposable
     /// </summary>
     public X509Certificate2 ServerCertificate { get; }
 
-    private readonly Socket listenerV4;
-    private readonly Socket? listenerV6;
+    private readonly Socket primaryListener;
+    private readonly Socket? secondaryListener;
     private readonly X509Certificate2 certificate;
+
+    /// <summary>
+    /// True when the listener generated <see cref="certificate"/> itself and
+    /// must dispose it; false when the certificate was supplied through the
+    /// listen options, whose caller retains ownership.
+    /// </summary>
+    private readonly bool ownsCertificate;
+
     private readonly CancellationTokenSource stopSource = new();
     private readonly ConcurrentDictionary<TdsSession, byte> sessions = new();
     private int disposed;
 
-    internal SimulatedNetworkListener(Simulation simulation, Socket listenerV4, Socket? listenerV6, X509Certificate2 certificate, int port)
+    internal SimulatedNetworkListener(Simulation simulation, Socket primaryListener, Socket? secondaryListener, X509Certificate2 certificate, bool ownsCertificate, int port)
     {
-        this.listenerV4 = listenerV4;
-        this.listenerV6 = listenerV6;
+        this.primaryListener = primaryListener;
+        this.secondaryListener = secondaryListener;
         this.certificate = certificate;
+        this.ownsCertificate = ownsCertificate;
         this.ServerCertificate = X509CertificateLoader.LoadCertificate(certificate.Export(X509ContentType.Cert));
         this.Port = port;
 
-        _ = this.AcceptLoopAsync(simulation, listenerV4);
-        if (listenerV6 is not null)
-            _ = this.AcceptLoopAsync(simulation, listenerV6);
+        _ = this.AcceptLoopAsync(simulation, primaryListener);
+        if (secondaryListener is not null)
+            _ = this.AcceptLoopAsync(simulation, secondaryListener);
     }
 
     /// <summary>
@@ -69,12 +79,13 @@ public void Dispose()
             return;
 
         this.stopSource.Cancel();
-        this.listenerV4.Dispose();
-        this.listenerV6?.Dispose();
+        this.primaryListener.Dispose();
+        this.secondaryListener?.Dispose();
         foreach (var session in this.sessions.Keys)
             session.Abort();
 
-        this.certificate.Dispose();
+        if (this.ownsCertificate)
+            this.certificate.Dispose();
         this.ServerCertificate.Dispose();
         this.stopSource.Dispose();
     }

src/SqlServerSimulator/SimulatedNetworkListenerOptions.cs

@@ -0,0 +1,49 @@
+using System.Net;
+using System.Security.Cryptography.X509Certificates;
+
+namespace SqlServerSimulator;
+
+/// <summary>
+/// Configuration for the listen methods on <see cref="Simulation"/>, accepted
+/// by the options overloads of
+/// <see cref="Simulation.ListenLocalAsync(SimulatedNetworkListenerOptions, CancellationToken)"/>
+/// and
+/// <see cref="Simulation.ListenNetworkAsync(SimulatedNetworkListenerOptions, CancellationToken)"/>.
+/// </summary>
+public sealed class SimulatedNetworkListenerOptions
+{
+    /// <summary>
+    /// The TCP port to bind, 1433 by default. Pass 0 to let the operating
+    /// system assign an ephemeral port, reported by the listener's port
+    /// property — the right choice for parallel test runs.
+    /// </summary>
+    public int Port { get; init; } = 1433;
+
+    /// <summary>
+    /// A single interface address for
+    /// <see cref="Simulation.ListenNetworkAsync(SimulatedNetworkListenerOptions, CancellationToken)"/>
+    /// to bind instead of all interfaces — exactly this address, with no
+    /// best-effort second-family sibling. Null (the default) keeps each
+    /// method's standard binding: the loopback pair for the local method,
+    /// the all-interfaces pair for the network method. Only the network
+    /// method honors it;
+    /// <see cref="Simulation.ListenLocalAsync(SimulatedNetworkListenerOptions, CancellationToken)"/>
+    /// raises <see cref="ArgumentException"/> for a non-null value, because
+    /// loopback-only is its contract — its accept-anyone-until-a-login-exists
+    /// credential model must never face a network interface.
+    /// </summary>
+    public IPAddress? BindAddress { get; init; }
+
+    /// <summary>
+    /// The TLS certificate the listener presents during the handshake, which
+    /// must include a private key (a certificate without one raises
+    /// <see cref="ArgumentException"/>). The caller retains ownership — the
+    /// listener never disposes a supplied certificate — so one certificate
+    /// can serve many listeners: created once at suite setup and, for
+    /// <c>Encrypt=Strict</c> clients, exported once to a file that connection
+    /// strings pin via the <c>ServerCertificate</c> keyword. Null (the
+    /// default) generates an ephemeral self-signed certificate that lives and
+    /// dies with the listener.
+    /// </summary>
+    public X509Certificate2? ServerCertificate { get; init; }
+}