feat(auth)!: ScadaBridge retire SQL Server ApiKey entity + ApprovedApiKeyIds + legacy hashing; EF migration RetireInboundApiKeyStore; re-issue runbook + CHANGELOG (re-arch C5/E) — BREAKING: X-API-Key -> Bearer sbk_, keys re-issued

2026-06-02 05:39:59 -04:00
parent b13d7b3d28
commit afa55981d5
32 changed files with 2117 additions and 1193 deletions
@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to ScadaBridge are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Changed — BREAKING: inbound API authentication
+
+Inbound API authentication has migrated off the SQL Server `X-API-Key` scheme and
+onto the shared `ZB.MOM.WW.Auth.ApiKeys` library.
+
+- **Credential format.** The inbound `POST /api/{methodName}` endpoint now
+  authenticates an `Authorization: Bearer sbk_<keyId>_<secret>` token instead of the
+  raw `X-API-Key: <key>` header. The secret is verified with a peppered, constant-time
+  HMAC compare inside the shared library verifier.
+- **Storage.** Inbound API keys now live in the shared `ZB.MOM.WW.Auth.ApiKeys` SQLite
+  store, not the SQL Server configuration database. The deterministic-HMAC `ApiKey`
+  table is gone.
+- **Authorization model.** A key's allowed methods are now its per-key **scopes**
+  (scope string == method name, ordinal/case-sensitive). The previous
+  `ApiMethod.ApprovedApiKeyIds` CSV that linked methods to key IDs has been removed.
+- **Peppering.** Keys are peppered per environment via
+  `ScadaBridge:InboundApi:ApiKeyPepper` (≥ 16 characters, **different per environment**,
+  kept secret). The same configuration key now backs the library verifier's pepper
+  secret.
+
+> **BREAKING — all existing inbound API keys are INVALIDATED and must be re-issued.**
+> Old `X-API-Key` credentials and their stored HMAC hashes are not migrated and are
+> not recoverable; the `ApiKeys` table is dropped. Operators must re-issue every
+> inbound key as an `sbk_…` token and update every API client. See the runbook:
+> [`docs/operations/inbound-api-key-reissue.md`](docs/operations/inbound-api-key-reissue.md).
+
+### Removed
+
+- The SQL Server `ApiKey` entity (`ZB.MOM.WW.ScadaBridge.Commons.Entities.InboundApi.ApiKey`),
+  its EF Core mapping, and its `IInboundApiRepository` key methods
+  (`GetApiKeyByIdAsync`, `GetAllApiKeysAsync`, `GetApiKeyByValueAsync`, `AddApiKeyAsync`,
+  `UpdateApiKeyAsync`, `DeleteApiKeyAsync`, `GetApprovedKeysForMethodAsync`).
+- The `ApiMethod.ApprovedApiKeyIds` property, its EF mapping, and the CSV
+  parse/serialize helpers.
+- The legacy hashing code: `ApiKeyHasher` / `IApiKeyHasher` and the in-repo inbound
+  `ApiKeyValidator` (superseded by the shared `IApiKeyVerifier`), plus their DI
+  registrations and tests.
+
+### Migrations
+
+- `RetireInboundApiKeyStore` — drops the `ApiKeys` table and the
+  `ApiMethods.ApprovedApiKeyIds` column. `Down` recreates both, but **dropped keys are
+  not recoverable**: rolling the migration back does not restore credentials. Rollback
+  means reverting the deployment, then re-issuing keys.