ScadaBridge/CHANGELOG.md

# 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/).

Detailed per-change history lives in `git log`,
`archreview/plans/00-MASTER-TRACKER.md`, and `docs/plans/` — this file records
operator-facing and breaking changes only.

## [Unreleased]

### Changed — Architecture-review hardening initiative (PLAN-01…PLAN-08, 2026-07-08 → 2026-07-10)

Eight architecture reviews produced eight fix plans; 191 of 192 tasks landed. The
initiative added eager startup options-validation across 12+ components, ClusterClient
message-contract lock tests, secured-write pending-TTL, a login throttle, transport
import single-flight, store-and-forward sweep bounding, and a deploy-readiness
handshake; it excised the vestigial site-notification delivery surface and established
a canonical deferred-work register. Authoritative record:
`archreview/plans/00-MASTER-TRACKER.md` plus the per-plan docs.

### Added — M8 Transport

Encrypted bundle export/import extended from central-only config to site/instance-scoped
config (`Site`s, site `DataConnection`s, `Instance`s + `Area` by name), reconciled across
environments by the `BundleNameMap` name-mapping subsystem, with a per-line Myers diff and
the script trust gate enforced at import review. Post-initiative additions (both 2026-07-10):
an aggregated live alarm stream feeding the Alarm Summary page, and hourly KPI rollups
unblocking 30d/90d trend windows.

### Added — M7 Native alarms + operational UX

Read-only native-alarm mirroring (OPC UA Alarms & Conditions + MxAccess Gateway) onto a
unified condition model; an operator Alarm Summary page; OPC UA node browse/search/type-info
and site-local certificate trust; **two-person secured writes, introducing the `Operator`
and `Verifier` roles**; and an SMS (Twilio) notification delivery adapter.

### Changed — BREAKING: canonical role names + audit separation-of-duties collapse (Task 1.7)

Role string VALUES are standardized onto the canonical vocabulary
(`Administrator`/`Designer`/`Deployer`/`Viewer`; `Engineer` remains unused by
ScadaBridge; `Operator` has since been adopted by the M7 two-person secured-write
flow, together with the new `Verifier` role — see the M7 entry above). The legacy
ScadaBridge role names were renamed and two were
**collapsed**:

| Legacy role     | Canonical role  | Notes |
|-----------------|-----------------|-------|
| `Admin`         | `Administrator` | rename |
| `Design`        | `Designer`      | rename |
| `Deployment`    | `Deployer`      | rename |
| `Audit`         | `Administrator` | **COLLAPSE** |
| `AuditReadOnly` | `Viewer`        | **COLLAPSE** |

- **SECURITY — privilege escalation (accepted).** The former `Audit` role
  collapses into `Administrator`. This is a real escalation: a former audit-only
  user now holds the **entire admin surface** (create/update/delete sites, manage
  LDAP group→role mappings and API keys, preview/import transport bundles), not
  just audit read+export. This loss of auditor/admin separation-of-duties is a
  deliberate, accepted trade-off of the canonicalization.
- **SECURITY — half-SoD preserved.** The former `AuditReadOnly` role collapses
  into `Viewer`, which **keeps audit READ** (Audit Log page, Configuration Audit
  Log page, audit nav group) but **cannot bulk-export**. The audit policy sets are
  now `OperationalAuditRoles = { Administrator, Viewer }` and
  `AuditExportRoles = { Administrator }`, so a `Viewer` reads the audit log but the
  Export-CSV button / `/api/audit/export` endpoint correctly refuses it.
- **Enforcement.** Every enforcement site moved together: the role-claim values,
  the authorization policies (`RequireAdmin`/`RequireDesign`/`RequireDeployment`
  policy *names* are unchanged; only the role *values* inside them changed), the
  `ManagementActor.GetRequiredRole` switch, the hard-coded site-scope admin-bypass
  (`Roles.Administrator` everywhere), the `DebugStreamHub` Administrator/Deployer
  gates, and the CentralUI `BrowseService`/`BindingTester` Designer guards.
  **Site-scoping logic is otherwise unchanged** — only the admin-bypass *value*
  moved from `"Admin"` to `Roles.Administrator`.
- **Config-DB migration `CanonicalizeRoles`.** Updates the four seeded
  `LdapGroupMappings` rows (Id 1-4) to the canonical role values and adds raw
  idempotent catch-all `UPDATE`s for operator-added rows
  (`Admin`/`Audit`→`Administrator`, `Design`→`Designer`, `Deployment`→`Deployer`,
  `AuditReadOnly`→`Viewer`). The Down migration is **lossy** for the collapse: it
  best-effort maps `Administrator`→`Admin` and `Viewer`→`AuditReadOnly` but cannot
  recover the original `Audit`/`Admin` or `Viewer`/`AuditReadOnly` distinction.
- **Operator action.** Any LDAP group→role mappings created with the legacy role
  strings are migrated automatically by `CanonicalizeRoles`. New mappings created
  via the CentralUI LDAP-mappings form now offer the canonical role values
  (including a `Viewer` option for audit-read-only delegation).

### 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.