release: 0.10.1 (thorough-review maintenance tier + Abstractions 0.16.0)

CHANGELOG.md

@@ -19,6 +19,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+## [0.10.1] - 2026-07-24
+
+Maintenance release: the deferred "thorough-review" hardening tier plus the
+`Wolfgang.Etl.Abstractions` 0.17.0 bump. **No public API or behaviour change** to
+either shipped package — the test doubles and contract-test base classes are
+unchanged.
+
+### Changed
+
+- Built against `Wolfgang.Etl.Abstractions` 0.17.0 (was 0.15.0).
+
+### Security
+
+- Release now publishes via **OIDC / NuGet Trusted Publishing** (`NuGet/login`), removing
+  the long-lived `NUGET_API_KEY` from the release path.
+- Added supply-chain / security CI: transitive-dependency **license audit**, **CycloneDX SBOM**,
+  **OSSF Scorecard**, **Semgrep** SAST, GitHub **Actions audit** (actionlint + zizmor, all
+  actions SHA-pinned), and **build-reproducibility** verification with a per-release
+  reproducible-build manifest attached to each GitHub Release.
+- Documented the release path and compromise scope in `SECURITY.md`, and added a
+  consumer-side reproducible-build verification guide (`docs/REPRODUCIBLE-BUILD.md`).
+
 ## [0.10.0] - 2026-06-29
 
 Adds an opt-in contract-test base for the `ISupportDryRun` interface introduced in

README.md

@@ -9,6 +9,7 @@ An Extractor, Transformer and Loader designed to be used in testing libraries bu
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![.NET](https://img.shields.io/badge/.NET-Multi--Targeted-purple.svg)](https://dotnet.microsoft.com/)
 [![GitHub](https://img.shields.io/badge/GitHub-Repository-181717?logo=github)](https://github.com/Chris-Wolfgang/ETL-Test-Kit)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Chris-Wolfgang/ETL-Test-Kit/badge)](https://scorecard.dev/viewer/?uri=github.com/Chris-Wolfgang/ETL-Test-Kit)
 
 ---
 
@@ -239,17 +240,15 @@ public sealed class MyLoaderContractTests
 
 ---
 
-## 🎯 Target Frameworks
+## 🎯 Supported Frameworks
 
-Both packages multi-target the following frameworks:
+This library targets:
 
-| Framework | Versions |
-|-----------|----------|
-| .NET Framework | .NET 4.6.2, .NET 4.8.1 |
-| .NET Standard | .NET Standard 2.0 |
-| .NET | .NET 8.0, .NET 10.0 |
+- **.NET Framework:** 4.6.2, 4.8.1
+- **.NET Standard:** 2.0
+- **.NET:** 8.0, 10.0
 
----
+See the [NuGet package page](https://www.nuget.org/packages/Wolfgang.Etl.TestKit/) for the authoritative per-TFM compatibility matrix.
 
 ## 🔍 Code Quality & Static Analysis
 
@@ -357,6 +356,16 @@ docfx build --serve
 
 ---
 
+## 🔐 Verify the build
+
+Every release is built deterministically, and each GitHub Release attaches a
+`reproducible-build-manifest.json` with the SHA-256 of every shipped assembly.
+You can independently rebuild from the tag and confirm the hashes match — see
+[docs/REPRODUCIBLE-BUILD.md](docs/REPRODUCIBLE-BUILD.md) for the step-by-step
+procedure and how to publish a third-party attestation.
+
+---
+
 ## 🤝 Contributing
 
 Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:

REPRODUCIBLE-BUILD.md

@@ -0,0 +1,50 @@
+# Reproducible builds
+
+Both shipped assemblies — `Wolfgang.Etl.TestKit` and `Wolfgang.Etl.TestKit.Xunit`
+— are built to be **byte-for-byte reproducible**: the same source commit produces
+the same compiled output regardless of *where* it is built.
+
+## What makes the build reproducible
+
+`Directory.Build.props` sets the compiler inputs that a reproducible build
+requires:
+
+- `<Deterministic>true</Deterministic>` — the compiler emits deterministic
+  output (no embedded timestamps, ordered metadata).
+- `<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>` (in CI) —
+  normalises embedded source paths to a deterministic `/_/` root via `PathMap`,
+  so the checkout directory does not leak into the assembly.
+- SourceLink — embeds the commit SHA rather than machine-local paths.
+
+## How it is verified
+
+[`.github/workflows/reproducible-build.yaml`](.github/workflows/reproducible-build.yaml)
+checks the same commit out to two independent directories, builds each with
+`-p:ContinuousIntegrationBuild=true`, and fails if the produced `.dll`s do not
+hash identically (`sha256sum`). This proves **path-independent** reproducibility
+on a single runner — the property that lets a third party rebuild and match.
+
+## How to verify it yourself
+
+```bash
+git clone https://github.com/Chris-Wolfgang/ETL-Test-Kit a
+git clone https://github.com/Chris-Wolfgang/ETL-Test-Kit b
+for d in a b; do
+  dotnet build "$d/src/Wolfgang.Etl.TestKit/Wolfgang.Etl.TestKit.csproj" \
+    -c Release -f net10.0 -p:ContinuousIntegrationBuild=true
+done
+sha256sum \
+  a/src/Wolfgang.Etl.TestKit/bin/Release/net10.0/Wolfgang.Etl.TestKit.dll \
+  b/src/Wolfgang.Etl.TestKit/bin/Release/net10.0/Wolfgang.Etl.TestKit.dll
+# The two hashes must be identical.
+```
+
+## Scope / follow-up
+
+The verification above covers path-independent reproducibility on a single OS —
+the fleet-proven guarantee. **Cross-OS** byte-identity (building on Ubuntu vs
+Windows and matching) is a stronger claim that is not yet asserted here: `.pdb`
+and some embedded metadata can differ across SDK patch levels and operating
+systems even with deterministic inputs. Extending the matrix to cross-OS
+comparison (with any required `.pdb`/metadata normalisation) is tracked as a
+follow-up to #135.

SECURITY.md

@@ -21,3 +21,15 @@ We will acknowledge your report within 48 hours and provide an estimated timelin
 
 Your help is greatly appreciated!
 Responsible disclosure of security vulnerabilities helps protect our entire community.
+
+## Release path & compromise scope
+
+Facts a maintainer would need at 2am if the release identity is compromised. Generic incident-response steps (rotating credentials, revoking OAuth apps, publishing advisories, unlisting NuGet packages) are not duplicated here — GitHub's and NuGet's own docs update faster than a checked-in runbook.
+
+- **Release path**: OIDC / NuGet Trusted Publishing via `NuGet/login@v1` in `.github/workflows/release.yaml`. The workflow mints an ephemeral push token per run via OIDC — the release path does not depend on a long-lived API key stored in GitHub secrets or on the NuGet account. During an incident, check the NuGet account for any long-lived API keys anyway (they can be created outside of CI) and delete anything you don't recognize.
+- **Fallback**: none. If Trusted Publishing is compromised, the incident is at the GitHub-account level (the OIDC identity is `Chris-Wolfgang/ETL-Test-Kit`).
+- **Owner**: @Chris-Wolfgang.
+- **Downstream consumers**: known Wolfgang.* dependents (test projects) include ETL-Xml, ETL-FixedWidth, Etl-DbClient, ETL-Json, and ETL-Transformers; unknown external consumers may also exist on nuget.org.
+- **Package coordinates for unlisting**: this repo ships two packages —
+  - `Wolfgang.Etl.TestKit` — https://www.nuget.org/packages/Wolfgang.Etl.TestKit/
+  - `Wolfgang.Etl.TestKit.Xunit` — https://www.nuget.org/packages/Wolfgang.Etl.TestKit.Xunit/

docfx_project/docfx.json

@@ -1,65 +1,65 @@
-{
-  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
-  "metadata": [
-    {
-      "src": [
-        {
-          "files": [
-            "src/**/*.csproj"
-          ],
-          "src": "../"
-        }
-      ],
-      "dest": "api",
-      "properties": {
-        "TargetFramework": "net8.0"
-      },
-      "disableGitFeatures": false,
-      "disableDefaultFilter": false
-    }
-  ],
-  "build": {
-    "content": [
-      {
-        "files": [
-          "**/*.{md,yml}"
-        ],
-        "exclude": [
-          "_site/**"
-        ]
-      }
-    ],
-    "resource": [
-      {
-        "files": [
-          "logo.svg",
-          "apple-touch-icon.png",
-          "favicon.svg",
-          "favicon.ico",
-          "images/**",
-          "public/**",
-          "versions.json"
-        ]
-      }
-    ],
-    "output": "_site",
-    "template": [
-      "default",
-      "modern"
-    ],
-    "globalMetadata": {
-      "_appName": "Wolfgang.Etl.TestKit",
-      "_appTitle": "Wolfgang.Etl.TestKit Documentation",
-      "_appLogoPath": "logo.svg",
-      "_appFaviconPath": "favicon.svg",
-      "_enableSearch": true,
-      "_appFooter": "Made with DocFX <script>(function(){var r='/';if(window.location.hostname.endsWith('.github.io')){var s=window.location.pathname.split('/').filter(Boolean);if(s.length)r='/'+s[0]+'/';}var t=document.createElement('script');t.src=r+'public/version-picker.js';t.async=true;document.head.appendChild(t);})();</script>",
-      "_disableSidebar": false,
-      "_disableTocFilter": false,
-      "_enableDarkMode": true,
-      "colorMode": "dark",
-      "_baseUrl": "https://Chris-Wolfgang.github.io/ETL-Test-Kit/",
-      "pdf": true
-    }
-  }
-}
+{
+  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [
+            "src/**/*.csproj"
+          ],
+          "src": "../"
+        }
+      ],
+      "dest": "api",
+      "properties": {
+        "TargetFramework": "net8.0"
+      },
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "**/*.{md,yml}"
+        ],
+        "exclude": [
+          "_site/**"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "logo.svg",
+          "apple-touch-icon.png",
+          "favicon.svg",
+          "favicon.ico",
+          "images/**",
+          "public/**",
+          "versions.json"
+        ]
+      }
+    ],
+    "output": "_site",
+    "template": [
+      "default",
+      "modern"
+    ],
+    "globalMetadata": {
+      "_appName": "Wolfgang.Etl.TestKit",
+      "_appTitle": "Wolfgang.Etl.TestKit Documentation",
+      "_appLogoPath": "logo.svg",
+      "_appFaviconPath": "favicon.svg",
+      "_enableSearch": true,
+      "_appFooter": "Made with DocFX <script>(function(){var r='/';if(window.location.hostname.endsWith('.github.io')){var s=window.location.pathname.split('/').filter(Boolean);if(s.length)r='/'+s[0]+'/';}var t=document.createElement('script');t.src=r+'public/version-picker.js';t.async=true;document.head.appendChild(t);})();</script>",
+      "_disableSidebar": false,
+      "_disableTocFilter": false,
+      "_enableDarkMode": true,
+      "colorMode": "dark",
+      "_baseUrl": "https://Chris-Wolfgang.github.io/ETL-Test-Kit/",
+      "pdf": true
+    }
+  }
+}

docs/REPRODUCIBLE-BUILD.md

@@ -0,0 +1,91 @@
+# Verifying the build is reproducible
+
+Every release of `Wolfgang.Etl.TestKit` and `Wolfgang.Etl.TestKit.Xunit` is built
+deterministically: the same source at the same tag produces byte-identical
+assemblies, independent of who builds it or where. This page lets **you** confirm
+that independently, so "our builds are reproducible" is a checkable claim rather
+than a promise.
+
+CI already proves *same-environment* reproducibility on every push
+([`reproducible-build.yaml`](../.github/workflows/reproducible-build.yaml), #135):
+it builds the library twice and asserts the assembly hashes match. This document
+is the *consumer-side* flip — how a third party reproduces and attests to it.
+
+## What is published
+
+Each GitHub Release attaches a **`reproducible-build-manifest.json`** listing the
+SHA-256 of every shipped assembly, plus the reference environment (OS and .NET SDK
+version) and the exact build command used to produce them. Example:
+
+```json
+{
+  "schema": "wolfgang.reproducible-build-manifest/v1",
+  "version": "v0.11.0",
+  "targetFramework": "net10.0",
+  "buildCommand": "dotnet build <project> -c Release -f net10.0 -p:ContinuousIntegrationBuild=true",
+  "referenceEnvironment": { "os": "Linux", "dotnetSdk": "10.0.110" },
+  "assemblies": [
+    { "assembly": "Wolfgang.Etl.TestKit.dll", "sha256": "…" },
+    { "assembly": "Wolfgang.Etl.TestKit.Xunit.dll", "sha256": "…" }
+  ]
+}
+```
+
+## Reproduce it yourself
+
+1. **Match the reference environment.** Use the same OS family and .NET SDK
+   version named in the release's manifest (`referenceEnvironment`).
+   `ContinuousIntegrationBuild=true` normalises source paths, so the *checkout
+   location* does not matter — but the compiler version does, so match the SDK.
+
+2. **Clone at the exact tag:**
+
+   ```bash
+   git clone --branch <tag> --depth 1 https://github.com/Chris-Wolfgang/ETL-Test-Kit
+   cd ETL-Test-Kit
+   ```
+
+3. **Build each library with the documented command** (the manifest's
+   `buildCommand`):
+
+   ```bash
+   dotnet build src/Wolfgang.Etl.TestKit/Wolfgang.Etl.TestKit.csproj \
+     -c Release -f net10.0 -p:ContinuousIntegrationBuild=true
+   dotnet build src/Wolfgang.Etl.TestKit.Xunit/Wolfgang.Etl.TestKit.Xunit.csproj \
+     -c Release -f net10.0 -p:ContinuousIntegrationBuild=true
+   ```
+
+4. **Hash your output and compare** against the manifest:
+
+   ```bash
+   sha256sum \
+     src/Wolfgang.Etl.TestKit/bin/Release/net10.0/Wolfgang.Etl.TestKit.dll \
+     src/Wolfgang.Etl.TestKit.Xunit/bin/Release/net10.0/Wolfgang.Etl.TestKit.Xunit.dll
+   ```
+
+   Each hash must equal the corresponding `sha256` in
+   `reproducible-build-manifest.json`. The repo's own generator
+   ([`scripts/reproducible-manifest.sh`](../scripts/reproducible-manifest.sh))
+   runs exactly these steps, so you can also regenerate the whole manifest and
+   `diff` it against the published one.
+
+## If a hash does not match
+
+A mismatch means either the environments differ (most commonly a different SDK
+patch version) or the artifact was tampered with. Please
+[open an issue](https://github.com/Chris-Wolfgang/ETL-Test-Kit/issues/new) titled
+"Reproducible-build mismatch for `<tag>`" including:
+
+- the release tag,
+- your OS and `dotnet --version`,
+- your computed hashes vs the manifest's,
+- the exact commands you ran.
+
+## Publishing a third-party attestation
+
+Independent verification is most useful when it is *public*. If you reproduced a
+release successfully, you can publish an attestation following the
+[Reproducible Builds project](https://reproducible-builds.org/) conventions (or a
+service such as [vouchsafe.io](https://vouchsafe.io/)): sign a statement naming the
+tag, the manifest hash, and your environment, and link it back on the mismatch/
+verification issue so others can find corroborating rebuilds.

docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,27 @@
+# 1. Record architecture decisions
+
+## Status
+
+Accepted
+
+## Context
+
+Wolfgang.Etl.TestKit is a small but long-lived pair of NuGet packages (the test
+doubles and the xUnit contract-test base classes) maintained across many release
+cycles, often by different contributors and automated agents. Several non-obvious
+design choices — the pinned `AssemblyVersion`, the split into two packages, the
+injectable progress timer — are easy to accidentally undo in a later change
+because the *reasoning* lives only in commit messages or a reviewer's memory.
+
+## Decision
+
+We will keep Architecture Decision Records in `docs/adr/`, one Markdown file per
+decision, in the Nygard format (Context / Decision / Consequences). Records are
+immutable once accepted; a changed decision is captured as a new, superseding ADR.
+
+## Consequences
+
+- The rationale behind load-bearing choices is discoverable next to the code.
+- Reviewers can point at an ADR instead of re-litigating a settled decision.
+- There is a small ongoing cost: a genuinely architectural change should come
+  with an ADR, not just code.