Compare commits

...

660 Commits

Author SHA1 Message Date
Joseph Doherty bfc369062c deploy(prod): stage the PROD install pack on app-vp03/04 + par-vp03/04 over SMB (nothing executed)
Configs, env templates, install wrappers (dry/real, never start), SQL (65-migration schema, zbsecrets v1, _PROD role rows),
preflight, seed script, patched mxgw Install script (worker name, file KEK, connstr mask). Plan: Phase 3 gate corrected.

Claude-Session: https://claude.ai/code/session_01GT67AD5mc2BnaaAfY3hqqQ
2026-11-19 17:26:12 -05:00
Joseph Doherty 7261b18539 docs(plan): PROD LDAP decisions D-P5..D-P7 = as QA (svc_igntadmin bind, HIST_ADMIN_PROD->Deployer, RequireHttpsCookie=false)
Claude-Session: https://claude.ai/code/session_01GT67AD5mc2BnaaAfY3hqqQ
2026-11-19 16:35:20 -05:00
Joseph Doherty 8e415212fa docs(plan): PROD install gets the NAM AD LDAP settings (§3A): block, _PROD mappings, secret before first start, D-P5..D-P7
Claude-Session: https://claude.ai/code/session_01GT67AD5mc2BnaaAfY3hqqQ
2026-11-19 16:24:04 -05:00
Joseph Doherty 9789b01acd deploy(ldap): QA vq03/vq04 NAM AD cutover executed with the DEV builds — HG, mxgw, ScadaBridge, OtOpcUa (record + scripts)
Claude-Session: https://claude.ai/code/session_01GT67AD5mc2BnaaAfY3hqqQ
2026-11-19 16:14:01 -05:00
Joseph Doherty 386c999720 deploy(ldap): keep the vd03 cutover helpers (otelgrep, sb-cli) for the QA run 2026-11-19 15:26:20 -05:00
Joseph Doherty 85915d8a57 docs(ldap): NAM plan §0Q — QA vq03/vq04 cutover (svc_igntadmin interim, DEV builds, one window) 2026-11-19 15:25:27 -05:00
Joseph Doherty c80d5e79a5 deploy(ldap): DEV vd03 NAM AD cutover executed — HG, mxgw, ScadaBridge, OtOpcUa (record + scripts) 2026-11-19 15:17:13 -05:00
Joseph Doherty b7ead15108 docs(ldap): NAM plan §0 — DEV vd03 cutover with today's groups and accounts (svc_igntadmin, dohertj2, HIST_ADMIN_DEV→Deployer interim) 2026-11-19 14:50:36 -05:00
Joseph Doherty 91d35edb9c docs(plan): PROD install of ScadaBridge + mxaccessgw (app-vp03/04 central, par-vp03/04 site)
Plan only, nothing executed. Records owner decisions (mxgw on all four boxes,
current main via QA, NAM AD LDAPS day one, signed QA bundle), the SMB-verified
box facts (admin account, subnets, .NET, MXAccess 6000.0045.2657.1; PAR boxes
wait on the WinPlatform deploy), phases 0-8, port matrix, rollback and open
questions.
2026-11-19 14:44:26 -05:00
Joseph Doherty b9d13e8856 docs(ldap): NAM plan §3.2 — no-role-no-login fixes merged (#913, #144, #145, historiangw#136), not deployed
Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
2026-11-17 11:49:02 -05:00
Joseph Doherty feb5463445 docs(ldap): NAM AD request list — add PROD (separate accounts, APP_DEPLOY_PROD, membership review), ticket checklist
Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
2026-11-17 11:03:13 -05:00
Joseph Doherty 74db4db08b docs(ldap): NAM AD request list — new accounts, new groups, groups to confirm, by env and app
Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
2026-11-17 11:01:33 -05:00
Joseph Doherty b8cecf309d docs(ldap): apply the 2026-11-15 independent review to the NAM cutover plan
Blockers: no-role-no-login family standard (OtOpcUa Phase A refuses empty and mapper-throws logins,
reversing Login_when_role_mapper_throws_signs_in_with_no_role_claims; new ScadaBridge Phase A2);
OtOpcUa validates only the FallbackServers + BindMode/UserBindTemplate rules (the library validator
would block boot on DEV's empty ServiceAccountDn). Majors: inject the library logger; shared-account
lockout model, no-lockout ask, value verification, canary, stop rule; DEV automation identity; rolling
standby-first restarts for config-only; HG case-sensitive GroupToRole (optional Phase A3); mxgw
config-bound cert pin. Minors and nits applied; review disposition table in section 11.

Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
2026-11-15 20:44:09 -05:00
Joseph Doherty 1d344a0c08 docs(ldap): rewrite the NAM AD cutover plan; one-group-one-role canonical mapping
- New plan docs/plans/2026-11-15-nam-ldap-cutover.md (supersedes the 2026-08-13 plan, now a pointer):
  current state per app/tier, Phase A OtOpcUa fix (ToLibraryOptions drops FallbackServers/BindMode/
  UserBindTemplate/AcceptDomainQualifiedNames; reflection completeness test), decisions D1-D7
  (dedicated service account scadaproj#58 = QA prerequisite), winrm deploy-scope runbook, idempotent
  ScadaBridge LdapGroupMappings SQL, corrections table.
- ldap_mapping.md rewritten as the canonical matrix under the rule 'one AD group grants exactly one
  role per app'; ScadaBridge Deployer moves to a new UG_WW_APP_DEPLOY_<T> group (was a two-row insert
  the unique index rejects).

Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
2026-11-15 20:28:09 -05:00
Joseph Doherty 2ed9bb4892 docs(index): ScadaBridge — leader-auto-down shipped default, #116 closed
Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
2026-11-15 19:59:21 -05:00
Joseph Doherty 489f6acb45 docs(index): ScadaBridge 061432c8 on DEV + QA — hash chain removed (#143), #116 QA drills done
Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
2026-11-15 19:36:57 -05:00
Joseph Doherty 32f55e8def docs(index): ScadaBridge — audit hash chain removed from main (IT security), #52 applied
Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
2026-11-15 17:52:01 -05:00
Joseph Doherty e06c11e7b0 Accept all 100 SCADA family UI consistency tasks 2026-11-14 02:36:01 -05:00
Joseph Doherty 5a3f39b05b test(ui): record owned OtOpcUa fixture cleanup 2026-11-14 02:23:55 -05:00
Joseph Doherty 6ef591ce13 Accept final OT grammar and inline-editor implementation 2026-11-14 02:21:22 -05:00
Joseph Doherty 7013b6ce65 Verify final OT route titles and official package byte graph 2026-11-14 02:18:05 -05:00
Joseph Doherty 65fa9137b8 test(ui): retain OtOpcUa component canaries and owned SQL proof 2026-11-14 02:03:08 -05:00
Joseph Doherty 06a3811331 Record final OT slice acceptance and integration findings 2026-11-14 01:46:48 -05:00
Joseph Doherty 34fc3ce7a9 Record independent OT route and existing runtime graph audit 2026-11-14 01:43:24 -05:00
Joseph Doherty 7db16e93ee Assemble open G3 evidence and explicit rollout limits 2026-11-14 01:31:11 -05:00
Joseph Doherty 4a8015d43a Reconcile GB ledger metadata with accepted seven-project evidence 2026-11-14 01:26:20 -05:00
Joseph Doherty a0d3b8a189 Prepare immutable source-only package status refresh 2026-11-14 01:25:46 -05:00
Joseph Doherty a8b4c35be2 Link original Impeccable review to implementation evidence 2026-11-14 01:23:07 -05:00
Joseph Doherty 88de7050a0 Apply VoiceOver exclusion to final OT acceptance scope 2026-11-14 01:21:00 -05:00
Joseph Doherty b4c24713b9 Record final OT caller checkpoints and BT peer evidence 2026-11-14 01:19:05 -05:00
Joseph Doherty 8aff5ece00 Record requested accessibility scope and Overview acceptance 2026-11-14 01:00:25 -05:00
Joseph Doherty 9796aa6b47 Document bounded common modal rollout observation 2026-11-14 00:17:52 -05:00
Joseph Doherty 827b282001 Record source package and repository status support for final gate 2026-11-14 00:14:38 -05:00
Joseph Doherty 738aa0b1c2 Accept canonical OT status and icon presentation 2026-11-14 00:04:41 -05:00
Joseph Doherty 261e3b6c41 Accept OT tree recovery and paused live tails 2026-11-13 23:46:38 -05:00
Joseph Doherty 8c11c7fdf1 Record OT deployment acceptance and refresh browser proof 2026-11-13 23:31:04 -05:00
Joseph Doherty 361226b24d Record BTDB chapter acceptance and remaining OT work 2026-11-13 23:20:02 -05:00
Joseph Doherty 75a1e6238e Record touch and keyboard acceptance with isolated SQL validation 2026-11-13 23:10:30 -05:00
Joseph Doherty 7ee65d9cd0 Accept OT navigation and track remaining consumer verification 2026-11-13 21:51:21 -05:00
Joseph Doherty fb40fec2d1 Verify Overview reflow and interactions in Firefox and WebKit 2026-11-13 21:36:28 -05:00
Joseph Doherty 33993296b3 Record OEE convergence and dialog identity acceptance 2026-11-13 21:26:35 -05:00
Joseph Doherty 117398cfd9 Record completed gateway and native OEE acceptance 2026-11-13 20:15:07 -05:00
Joseph Doherty 6dc8b003ba Accept interaction convergence and record split package rollout 2026-11-13 19:50:51 -05:00
Joseph Doherty 3c1eada677 test(ui): retain ScadaBridge synthetic consumer validation host 2026-11-13 19:43:32 -05:00
Joseph Doherty e61af09c2e Record verified producer and consumer execution checkpoints 2026-11-13 19:28:54 -05:00
Joseph Doherty bbc547e976 Release verified Secrets UI 1.0.1 metadata contrast patch 2026-11-13 19:27:25 -05:00
Joseph Doherty 596ba86232 fix(secrets-ui): use canonical metadata ink in supported palettes 2026-11-13 19:07:34 -05:00
Joseph Doherty aeb89047d8 docs(secrets-ui): verify exact published package delivery 2026-11-13 18:57:36 -05:00
Joseph Doherty 6b371becd4 docs(secrets): approve exact UI and contracts artifacts after review 2026-11-13 18:48:24 -05:00
Joseph Doherty bd257c6827 build(secrets-ui): freeze UI 1.0.0 package inputs 2026-11-13 17:56:57 -05:00
Joseph Doherty 447f3c8bf0 docs(ui): record accepted native pilot and consumer checkpoints 2026-11-13 17:52:31 -05:00
Joseph Doherty 46556dbb56 feat(secrets-ui): add metadata filtering and private reveal outcomes 2026-11-13 17:50:56 -05:00
Joseph Doherty 37cf0ff444 docs(theme): record stale candidate cache correction 2026-11-13 17:34:22 -05:00
Joseph Doherty f698f97889 feat(overview): adopt delivered theme patch and record UI validation 2026-11-13 17:32:32 -05:00
Joseph Doherty d8d633ddb2 fix(theme): preserve body styling for semantic row headers 2026-11-13 17:24:19 -05:00
Joseph Doherty 075cf47fc2 fix(theme): reflow KPI grid at narrow zoom widths 2026-11-13 17:22:58 -05:00
Joseph Doherty 5d2d9530ba fix(theme): allow canonical cards to reflow at narrow widths 2026-11-13 17:05:50 -05:00
Joseph Doherty 7aeb9c6545 feat(overview): add optional attention filter and explicit sweep zone 2026-11-13 17:03:56 -05:00
Joseph Doherty 510d15d546 fix(secrets-ui): align fields, confirmation lifecycle and list recovery 2026-11-13 17:02:22 -05:00
Joseph Doherty cb424a0ce7 fix(overview): expose complete diagnostics on keyboard and touch 2026-11-13 16:41:11 -05:00
Joseph Doherty b300784092 fix(overview): report freshness separately from reachability 2026-11-13 16:32:15 -05:00
Joseph Doherty 89e383a196 fix(overview): keep unknown check summaries neutral 2026-11-13 16:27:54 -05:00
Joseph Doherty e7b36a664b fix(overview): distinguish paused view from connection failure 2026-11-13 16:23:12 -05:00
Joseph Doherty f07bd3c776 fix(secrets-ui): isolate drafts and pending operations by editor target 2026-11-13 16:21:37 -05:00
Joseph Doherty be1ce9ef3a fix(overview): expose each health check state in text 2026-11-13 16:20:42 -05:00
Joseph Doherty 73e69ef2b8 docs(theme): accept immutable 1.0 release and local pilots 2026-11-13 16:17:12 -05:00
Joseph Doherty 70c5aa2b4d style(overview): adopt shared readable stale and status treatments 2026-11-13 16:12:46 -05:00
Joseph Doherty 3d61456d61 chore(theme): exclude generated browser helper bytecode 2026-11-13 15:49:20 -05:00
Joseph Doherty f8469aa837 feat(theme): implement accessible Technical-Light 1.0 contracts 2026-11-13 15:49:08 -05:00
Joseph Doherty 8969bee6a9 fix(theme): make shared status and supporting text readable 2026-11-13 15:36:57 -05:00
Joseph Doherty cf432c00bd docs(theme): define accessible theme release contract 2026-11-13 15:33:52 -05:00
Joseph Doherty 99f22b4148 test(ui): accept seven-project bUnit 2.7.2 migration 2026-11-13 15:32:41 -05:00
Joseph Doherty d36462ae7a docs(execution): record authorized checkout recovery 2026-11-13 15:15:53 -05:00
Joseph Doherty bb1c3ba97b docs(testing): record worktree blocker after three checks 2026-11-13 14:46:45 -05:00
Joseph Doherty c1334df736 docs(testing): record partial bUnit verification and open gate 2026-11-13 14:42:44 -05:00
Joseph Doherty 8232f3a9ee test(overview): migrate renderer fixtures to bUnit 2.7.2 2026-11-13 14:41:17 -05:00
Joseph Doherty f96104245e test(secrets): migrate UI fixtures to bUnit 2.7.2 2026-11-13 14:41:17 -05:00
Joseph Doherty 9bda64ec4b test(theme): verify bUnit 2.7.2 with patched DOM parser 2026-11-13 14:41:17 -05:00
Joseph Doherty 1118e0418e docs(ui): normalize review file endings 2026-11-13 14:40:42 -05:00
Joseph Doherty ad7b37d200 docs(ui): preserve family review and phased execution plan 2026-11-13 14:40:21 -05:00
Joseph Doherty 9c3ab5fcb7 docs(index): OtOpcUa v2 GA release-ready - G1 retired 2026-11-13 10:33:52 -05:00
Joseph Doherty 81c405292e docs(history): OtOpcUa G2/G7 recorded; vd03 config deploy e9fbe63e 2026-11-13 10:32:20 -05:00
Joseph Doherty 9c0a7cca46 docs(index): ScadaBridge QA vq03/vq04 audit hash chain enabled (#107, anchor 14:07:43Z, verify-chain Intact)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 09:13:23 -05:00
Joseph Doherty 238050eebf docs(index): OtOpcUa QA pair on Warm redundancy (#907); ScadaBridge QA WarmCanary connection, #138 gated live
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 09:01:57 -05:00
Joseph Doherty a274c3d824 docs(index): ScadaBridge 8e32f353 deployed to QA vq03/vq04 (migrations 58->64, #116 leader-auto-down, not drilled)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 08:14:22 -05:00
Joseph Doherty c398f36318 docs(index): OtOpcUa #615 closed — G5 signed off 2026-11-13 08:09:48 -05:00
Joseph Doherty 0914879915 docs(index): OtOpcUa 76e73e7d deployed to DEV vd03 + QA (#906 proven, #905, #717 inert, #900; lmxopcua#908)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 07:51:51 -05:00
Joseph Doherty 2717d7c23b docs(index): OtOpcUa #717 closed, #615 G9 PASS + G8 waived, Heidenhain accepted 2026-11-13 07:47:31 -05:00
Joseph Doherty 027eb354fd docs(index): deployed-state note — ScadaBridge vd03 now 8e32f353
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 07:22:14 -05:00
Joseph Doherty 029f4aab50 docs(index): ScadaBridge 8e32f353 deployed to DEV vd03, audit hash chain enabled (#107, #131, #139)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 07:22:00 -05:00
Joseph Doherty 65d8552584 docs(index): OtOpcUa pins HistorianGateway Client 1.1.0 (76e73e7d, lmxopcua#900)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 07:18:04 -05:00
Joseph Doherty 276260ae3b docs(localdb): 0.3.8 published and pinned in OtOpcUa + ScadaBridge (scadaproj#57)
Feed SHA256 prefixes: core 407ffd49, Contracts b397b6d8, Replication
d3e37254. Pins: OtOpcUa 47f0b98c, ScadaBridge 8e32f353.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 07:09:35 -05:00
Joseph Doherty 0be9e2ab97 docs(index): OtOpcUa #780 closed — QA scripted-alarm drill passed
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 06:54:19 -05:00
Joseph Doherty 14c29f48bf chore(localdb): bump to 0.3.8 (scadaproj#57)
Ships 3ddb083: sync streams end on ApplicationStopping and new streams
are refused Unavailable while stopping (lmxopcua#906). 262/262.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 06:40:58 -05:00
Joseph Doherty 3cb0104e88 docs(index): correct #717 test/mutation counts
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 03:46:05 -05:00
Joseph Doherty ee9b403c4f docs(index): OtOpcUa #717 Warm redundancy implemented default-off (f817c77e)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 03:45:46 -05:00
Joseph Doherty d5cb6ba2c0 docs(index): HistorianGateway 6365f34 deployed to DEV vd03 + QA vq04/vq03 (historiangw#135)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 03:36:44 -05:00
Joseph Doherty 2fe0582d7e docs(localdb): note unreleased #906 sync-stream shutdown fix (scadaproj#57)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 03:29:49 -05:00
Joseph Doherty 3ddb083b4c fix(localdb): end open sync streams on ApplicationStopping (lmxopcua#906)
LocalDbSyncService observed only the call token, which ASP.NET Core cancels
at the END of Kestrel's graceful drain. A peer's sync stream never ends on
its own, so every graceful stop of the passive node waited out the host's
whole ShutdownTimeout (30 s on OtOpcUa QA).

The service now takes an optional IHostApplicationLifetime (DI supplies it
in any generic host): ApplicationStopping is linked into the stream's token
and ends the session cleanly, and a stream arriving once stopping has begun
is refused Unavailable. Wire-compatible; no proto/schema change.

Tests: open stream ends within 5 s of StopApplication, new stream refused
Unavailable, control without a lifetime still running; both halves
mutation-killed. 262/262. Source only, NOT published (still 0.3.7).

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 03:29:31 -05:00
Joseph Doherty fa68b0ea02 docs(index): OtOpcUa #780 ScriptedAlarm seam on QA, vd03 runner flipped to OutOfProcess
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 03:15:51 -05:00
Joseph Doherty 65197ca1a2 docs(index): OtOpcUa c9640f5c deployed to DEV vd03 + QA vq03/vq04
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 02:58:23 -05:00
Joseph Doherty 127f07e1ef docs(glauth): LDAPS trust options, ldapwhoami gotcha, windev mxgw on :3894 (mxaccessgw#180)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 02:42:32 -05:00
Joseph Doherty 53013eb2d8 docs(index): OtOpcUa DEV vd03 at 6c4d2990 (read-only historian bindings); lmxopcua#700 closed
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 01:37:13 -05:00
Joseph Doherty 178ef651f9 docs(index): HistorianGateway Contracts + Client 1.1.0 published (historiangw#135)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 01:36:21 -05:00
Joseph Doherty 6d3fcaaa73 docs(index): mxaccessgw QA vq03/vq04 on 76a71bc8 (mxaccessgw#229, #170)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 23:48:32 -05:00
Joseph Doherty 4909946104 docs(overview): Phase 4 live acceptance complete - OtOpcUa one-Active + leader/split-brain chips pass (#14)
Re-ran the two design 9 checks that were blocked for OtOpcUa on 2026-07-24, against a
docker-dev rig from OtOpcUa master 412da27c (Health 0.3.0) with the dashboard in a
container on the rig network:

1. one Active per pair: exactly one /health/active 200 per mesh (MAIN central-2,
   SITE-A site-a-1, SITE-B site-b-1), dashboard shows one ACTIVE + one STANDBY each;
2. leader chip on every group; network-partitioning site-b-2 from site-b-1 produced
   two 1-member clusters, both Active, and the SPLIT BRAIN chip, which cleared once
   site-b-2 was restarted (healing the link alone does not merge two Akka clusters,
   the documented OtOpcUa recovery); stopping site-a-1 moved the SITE-A chip.

Evidence (screenshots, /health/active bodies, timeline) under
docs/plans/evidence/2026-11-12-overview-phase4/. Ledger task 20 -> completed (20/20).

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 22:47:13 -05:00
Joseph Doherty 2859d9ebfc docs(history): ScadaBridge OPC UA client on SDK 2.0.1 (ScadaBridge#125 closed, a2e9d718)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 22:24:07 -05:00
Joseph Doherty 41a5e4d187 docs(observability): Telemetry 0.3.1 published, adopted by all four apps, export spans gone at the collector (#56)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 22:21:07 -05:00
Joseph Doherty 71b8595742 feat(infra): per-box OTel collector on the wonder tiers; apps switched to OTLP (#54)
ZbOtelCollector (otelcol-contrib 0.162.0, NSSM, NT SERVICE\ZbOtelCollector, every
listener on 127.0.0.1, file + Prometheus exporters, size-capped rotation) on DEV
vd03 and QA vq03/vq04. OtOpcUa, ScadaBridge Central + Site, MxAccessGateway and
HistorianGateway export OTLP to http://127.0.0.1:4317 via two service-env entries
each; rolling restarts, standby-first on the QA pairs. Overview has no exporter
binding and is unchanged. Config, install/switch/verify scripts, runbook and the
dated rollout record under infra/otel-collector/wonder/; evidence doc, GAPS,
index row and deployment.md updated.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 22:10:15 -05:00
Joseph Doherty 85654d7b43 fix(telemetry): 0.3.1 OTLP export calls are not traced as client spans (#56)
The Serilog OTLP log sink is not part of the OTel SDK and does not run
inside SuppressInstrumentationScope, so every log batch produced a root
opentelemetry.proto.collector.logs.v1.LogsService/Export gRPC client span.

AddZbTelemetry now drops telemetry's own transport from tracing:
- HttpClient instrumentation: FilterHttpRequestMessage rejects export calls
- gRPC client instrumentation (no Filter option): the start-time
  EnrichWithHttpRequestMessage callback clears Recorded/IsAllDataRequested,
  which also leaves the child HTTP activity unsampled.
An export call is any /opentelemetry.proto.collector.* path, or an
OTLP/HTTP /v1/{traces,metrics,logs} path on the configured endpoint's
host:port (ZbOtlpExportCallFilter). Every other outgoing call keeps its span.

Tests: predicate theory + an end-to-end run against a loopback OTLP
receiver with positive controls (app gRPC + HttpClient calls traced) and
negatives (the real log-sink export, /v1/logs, gRPC path over HttpClient);
mutation-checked three ways.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 22:09:24 -05:00
Joseph Doherty d93ca7b8c2 docs(observability): ScadaBridge Central role over OTLP proven on the rig (ScadaBridge#133)
Metrics, traces and logs from both rig centrals with node.role=Central and site.id=central;
deployments.applied and inbound_api.requests arrive. Follow-ups scadaproj#56 (log-export
self-spans) and ScadaBridge#134 (rig image lacks git SHA).

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 21:49:33 -05:00
Joseph Doherty ca81dcbdd2 docs(observability): correct the 0.3.0 library commit SHAs after rebase (#55)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 21:29:37 -05:00
Joseph Doherty f05ce80269 docs(observability): Telemetry 0.3.0 published, adopted by all four apps, logs over OTLP proven (#55)
Evidence doc gains the #55 section (root cause of no logs, 0.3.0 contents + SHA256,
per-app commits, collector output per app: service.version, site.id, node.role and
log records on OtOpcUa, HistorianGateway, ScadaBridge Site and MxAccessGateway).
GAPS, current-state, SPEC, the Telemetry CLAUDE.md and the index row updated;
infra/otel-collector gains otelidentity.py (Resource per signal + log samples).

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 21:28:50 -05:00
Joseph Doherty 2011c8d6b9 feat(telemetry): 0.3.0 ApplyConfiguration reads an app's telemetry section (#55)
Exporter, OtlpEndpoint, ServiceVersion, SiteId, NodeRole, ExportLogs and
ResourceAttributes:<key> from <App>:Telemetry, absent keys keep code defaults, so
the four apps stop re-implementing the exporter parse and gain the identity keys.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 21:28:50 -05:00
Joseph Doherty cfc7168ace feat(telemetry): 0.3.0 service.version default, ResourceAttributes, logs follow AddZbTelemetry OTLP (#55)
- service.version: null ServiceVersion now defaults to the entry assembly's
  AssemblyInformationalVersion (the family apps stamp the git SHA there); "" omits it.
- ResourceAttributes: extra Resource attributes on every signal; first-class keys
  (service.*, host.name, site.id, node.role) are reserved and rejected at startup.
- Logs over OTLP: AddZbTelemetry publishes its options in DI and AddZbSerilog's OTLP
  log sink follows them when its own options do not select Otlp, so
  <App>:Telemetry:Exporter=Otlp now switches logs along with metrics and traces, with
  the same endpoint and Resource. ExportLogs=false opts out.
- Ships the unpublished 0.2.1 review fixes, including the stricter OTLP endpoint check
  (scheme-less host:port rejected when Exporter=Otlp); no app config sets an endpoint.
- Tests 42 -> 74, incl. a loopback OTLP/gRPC receiver proving logs arrive with the
  Resource, and an ExportLogs=false case with a metrics positive control.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 21:28:50 -05:00
Joseph Doherty 616e913f3e docs(index): mxaccessgw 76a71bc8 deployed on DEV vd03 (#226 + #228 verified live, mxaccessgw#229); QA pending
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 21:25:17 -05:00
Joseph Doherty e6a724ba8e docs(index): mxaccessgw #228 Write2 time-argument fix on main 9ef6fc84, deploy tracked #229
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 21:01:10 -05:00
Joseph Doherty e1a2df83f7 feat(infra): shared dev OTel collector; OTLP proven end to end for all four apps (#13)
- infra/otel-collector/: zb-otel-collector (otelcol-contrib 0.162.0) on 10.100.0.35 —
  OTLP gRPC :4317 / HTTP :4318, debug + file exporters, Prometheus re-export :8889,
  health :13133; README runbook + otelsum.py summariser. Deployed.
- components/observability/2026-11-12-otlp-end-to-end-evidence.md: metrics + traces
  received from OtOpcUa, HistorianGateway, ScadaBridge (Site) and MxAccessGateway;
  OtOpcUa Galaxy driver allowlist defect fixed in lmxopcua#892 (db86b996).
- GAPS.md, current-state banners, index row, Telemetry CLAUDE.md: #13 closed; follow-ups
  #54 (wonder-tier collector), #55 (resource identity + logs over OTLP), ScadaBridge#133
  (Central role). Telemetry 0.2.1 deliberately left unpublished (no lib change needed).

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 20:48:36 -05:00
Joseph Doherty f98ba08910 docs(index): Auth 0.5.0 published (ILdapGroupLookup; 0.4.2-0.4.4 first published), scadaproj#51 closed
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 20:11:16 -05:00
Joseph Doherty f5ef0efedd feat(auth): 0.5.0 passwordless group lookup ILdapGroupLookup (ScadaBridge#46)
ILdapGroupLookup.GetUserGroupsAsync(username, ct) re-reads a known user's
groups with the service account: same extraction, canonicalisation, endpoint
walk (FallbackServers), timeouts and TLS policy as AuthenticateAsync, via one
shared WalkEndpoints<T>. Explicit statuses: Found, UserNotFound, UserDisabled
(AD userAccountControl), AmbiguousUser, DirectoryUnavailable, NotSupported
(BindMode=User / no service account / foreign ILdapAuthService),
ProviderDisabled. AddZbLdapAuth registers it as the same singleton.

0.5.0 is the first published version carrying 0.4.2-0.4.4; scadaproj#51 was
live-verified against the NAM AD (24/24, identity check mutation-proven).

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 20:11:16 -05:00
Joseph Doherty 3ca7e1936f docs(deployment): QA HistorianGateway now fa9cf31 (historiangw#78)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 20:07:47 -05:00
Joseph Doherty 6c4595e87f docs(index): HistorianGateway fa9cf31 deployed to QA vq03/vq04 (historiangw#78 closed)
QA had no historian account and now reuses DEV's personal NAM account
(follow-up historiangw#134). Env migration: RuntimeDb removed,
LiveWritesEnabled on, gRPC 0.0.0.0:5221 kept.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 20:07:32 -05:00
Joseph Doherty f83c75678c docs(secrets): ignitionoee router is a deployed 0.6.2 consumer; store moved on CR (scadaproj#21)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 20:00:52 -05:00
Joseph Doherty 610c40afa5 docs(index): OtOpcUa QA canary, #890 re-apply, live #794 check and #780 runaway drill; #782/#801/#794/#890 closed
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 19:11:11 -05:00
Joseph Doherty cde1297c4a docs(index): OtOpcUa fea7de0a deployed on DEV vd03 and the QA pair vq03/vq04 (SDK 2.0.1, runner OutOfProcess on QA)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 17:05:06 -05:00
Joseph Doherty e6beb9b4bf docs(telemetry): Telemetry(.Serilog) 0.2.0 published; ScadaBridge on AddZbSerilog (ScadaBridge#94, scadaproj#12)
Both packages published to the feed 2026-11-12, packed from 01c6dc1 (the 0.2.0
code + corrected RepositoryUrl, before the 0.2.1 commit); SHA256 of the feed
download matches the local pack. ScadaBridge switched to AddZbSerilog with the
MinimumLevelGovernor + ConfigureLogger hooks (main 2d2e9f35) and deleted its
LoggerConfigurationFactory. Updates the Observability row, Telemetry/CLAUDE.md
and components/observability/GAPS.md.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 14:51:45 -05:00
Joseph Doherty e573ee40d5 docs(scadabridge-history): DCL OPC UA SDK 1.5.378.106 -> 1.5.378.182 (e36cd605), wire-compat vs SDK 1.5 + 2.0.1 servers; 2.0.x deferred (ScadaBridge#125)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 14:09:10 -05:00
Joseph Doherty ccfcc7c3d2 docs(index): LocalDb 0.3.7 published; ScadaBridge + OtOpcUa pin it (#53)
Published ZB.MOM.WW.LocalDb, .Contracts and .Replication 0.3.7 to the
Gitea feed (carrying the 0.3.5/0.3.6 changes); SHA256 recorded. Pins:
ScadaBridge main 12fa7aff (ScadaBridge#130), OtOpcUa master e3031654
(lmxopcua#889). Not deployed.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 14:07:58 -05:00
Joseph Doherty 470465dfbd docs(scadabridge-history): #129 alarm Severity one direction (dd4f1c2a), raw priority kept, MES deploy gate #131
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 14:06:09 -05:00
Joseph Doherty 30a12dd0fa docs(otopcua-history): #887 Galaxy alarm Severity follows AVEVA priority bands, 1 = most urgent (b61f3e05), consumer impact + ScadaBridge#129
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 12:19:09 -05:00
Joseph Doherty d5afd932e8 docs(otopcua-history): #886 Galaxy-backed folders serve AVEVA A&E history (3a312ffd), consumer impact
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 11:47:17 -05:00
Joseph Doherty a6d4d0d903 docs(otopcua-history): #879 EnabledSecurityProfiles replaces the default (a83bf1fa), consumer impact
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 11:39:24 -05:00
Joseph Doherty da4cb92713 docs(otopcua-history): wire ServiceLevel correct on SDK 2 (#884 claim, #885 startup 0); vd03 still 255 until redeployed
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 11:21:12 -05:00
Joseph Doherty d5de462f19 docs(otopcua-history): #880 SDK2 clients force legacy UserName encryption for 65-char keys vs SDK 1.5 servers (be28aa44), consumer impact
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 11:15:37 -05:00
Joseph Doherty 23693ef66c docs(otopcua-history): #882 folder event history includes attribute alarms (da948e5f), consumer impact
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 10:37:20 -05:00
Joseph Doherty 7c3d40ff19 docs(otopcua-history): drop unverified consumer example from #881 note
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 10:33:07 -05:00
Joseph Doherty 2624b32b1c docs(otopcua-history): #881 HistoryServerCapabilities flags per backend (b27b5b9c)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 10:32:49 -05:00
Joseph Doherty 3180b09659 docs(theme): Theme 0.5.3 published to the Gitea feed (unblocks ScadaBridge#61)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 08:51:34 -05:00
Joseph Doherty 9f7d36e7dc docs(index): mxaccessgw Contracts/Client 0.4.0 published; OtOpcUa adopts the stream-attached ack (lmxopcua#877)
Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 07:41:12 -05:00
Joseph Doherty ef1b835910 docs(index): mxaccessgw #227 stream-attached ack + #226 alarm UTC fix on main 2026-11-12 07:28:33 -05:00
Joseph Doherty d25b73bacd docs(deploy): vd03 HistorianGateway gRPC :5221 opened off-box (0.0.0.0 + firewall rule) 2026-11-12 07:04:47 -05:00
Joseph Doherty 24c2624ce5 docs(index): vd03 OtOpcUa #793 close-out — MaxRpm re-pointed (9adc5590), ACL off, no ScadaBridge OPC UA link 2026-11-12 06:16:30 -05:00
Joseph Doherty 1f23e8a965 docs(index): vd03 OtOpcUa upgraded to 5fb4b4db (#793); DEV inventory in deployment.md §9 2026-11-12 06:08:08 -05:00
Joseph Doherty 2e2ce62665 docs(history): correct vd03 Galaxy-ack note (no Galaxy driver deployed there) 2026-11-12 06:00:30 -05:00
Joseph Doherty 4735913cdc docs(history): OtOpcUa vd03 upgraded to 5fb4b4db (#793) 2026-11-12 06:00:23 -05:00
Joseph Doherty 2ff319197d docs(index): OtOpcUa master 31be927f — script-runner Windows pipe I/O (#789) 2026-11-11 21:11:23 -05:00
Joseph Doherty b322140b99 docs(index): OtOpcUa master f109e5f2 — Galaxy init budget (#875), #717 spec draft, gate F PASS 2026-11-11 19:01:36 -05:00
Joseph Doherty 81d8901bf0 docs(index): OtOpcUa master 43f8b8e8 — SDK server logging (#874), SDK2 clock-skew note (#873), integration CI green 2026-11-11 18:08:12 -05:00
Joseph Doherty 1c6fe5793b docs(index): vd03 DEV deploys 2026-11-11 — mxaccessgw 2b13564e, HistorianGateway ea9f21c, ScadaBridge 424db155 2026-11-11 16:50:58 -05:00
Joseph Doherty 601f7ae0e6 docs(index): OtOpcUa master 363f0d81 — Galaxy status mapping (#866/#872), ring event queue (#870) 2026-11-11 15:38:51 -05:00
Joseph Doherty d042890d50 docs(index): OtOpcUa master 7a27ef1f — Galaxy ack confirmation, host status, aggregates, folder events, hardware gates 2026-11-11 14:54:15 -05:00
Joseph Doherty d8147bd0fd docs(index): OtOpcUa master e857135e — Galaxy subscribe-reply race + reconnect fencing (#859/#861), #856–#862 batch 2026-11-11 11:29:07 -05:00
Joseph Doherty 2adcd75bdc docs(history): OtOpcUa #835–#854 docker-dev live gate PASS 2026-11-11 08:33:33 -05:00
Joseph Doherty 71b077c41b docs(index): OtOpcUa master 03e51457 — env: per-instance credentials, ConditionRefresh ordering (#848–#854) 2026-11-11 07:55:47 -05:00
Joseph Doherty 4ca420302f docs(index): OtOpcUa batches #815-#847 (credential lockout, scoped credential references) at d1b6cad2 2026-11-11 05:25:02 -05:00
Joseph Doherty b500618a55 index + history: OtOpcUa on HistorianGateway 1.0.0 (#131 closed) 2026-11-11 04:26:10 -05:00
Joseph Doherty 6cf69a00fb docs(index): OtOpcUa master 5bbe1e3c — Heidenhain LSV2 driver, narrow-grant UNS access (#808), batch #803–#814 2026-11-11 00:49:29 -05:00
Joseph Doherty 2dabb07a59 docs(index): OtOpcUa #796/#797/#798/#806 history — #797 scripted-alarm equipment-scope authorization 2026-11-10 22:31:37 -05:00
Joseph Doherty ed122145ed docs(index): record Linux OPC UA lifecycle diagnostic 2026-11-10 20:28:11 -05:00
Joseph Doherty 16418e48a0 docs(index): record SDK1 terminal server ownership repair 2026-11-10 17:14:53 -05:00
Joseph Doherty 805e3aac67 docs(index): record final SDK2 review and remaining release gates 2026-11-10 16:09:25 -05:00
Joseph Doherty aaa669f536 docs(index): mark historian TLS consumer migration verified 2026-11-10 14:52:08 -05:00
Joseph Doherty a33d8ecdfd docs(index): align current OtOpcUa master and gateway package pins 2026-11-10 14:50:56 -05:00
Joseph Doherty cbc7291f7b docs(index): record SDK2 candidate gates and HistorianGateway 1.0 consumer 2026-11-10 14:50:13 -05:00
Joseph Doherty 4c5a52d85f index + history: HistorianGateway Contracts/Client 1.0.0 released 2026-11-10 14:35:31 -05:00
Joseph Doherty 813ef65dbd historiangateway history: #58 closed (TLS secure by default), #131 filed 2026-11-10 14:13:45 -05:00
Joseph Doherty ccabcc68bc historiangateway history: #85 closed (rename-job polling) 2026-11-10 12:43:33 -05:00
Joseph Doherty 59bf74760c infra(glauth): enable LDAPS on :3894 alongside plain :3893 (#19, mxaccessgw#180)
Self-signed cert (SAN IP 10.100.0.35), public cert checked in, key host-only.
Deployed on 10.100.0.35: TLS chain verifies with the cert and fails without
it; raw LDAPS simple bind returns 0 for a good password and 49 for a bad one;
plain :3893 bind unchanged. README: thumbprint, client config, rotation; also
fixes the user-bind DN example (GLAuth puts users under their primary group OU).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-10 11:46:48 -05:00
Joseph Doherty 736158f2ad historiangateway history: #126 closed 2026-11-10 11:46:35 -05:00
Joseph Doherty bcbf1d006f historiangateway history: #115 live gate passed, #126 filed, #85/#58 status 2026-11-10 11:14:57 -05:00
Joseph Doherty e1ad6becb0 docs(index): record OtOpcUa HistorianGateway 0.4.0 consumption 2026-11-10 10:36:43 -05:00
Joseph Doherty 9f986e16e8 historiangateway history: CI not required to merge; #64 kit rail look 2026-11-10 10:27:31 -05:00
Joseph Doherty b3de2b7128 HistorianGateway: main branch protection + CI de-flake (historiangw#73) 2026-11-10 10:24:35 -05:00
Joseph Doherty fe5269208f HistorianGateway: native WriteLiveValues hardened (historiangw#25) 2026-11-10 10:00:56 -05:00
Joseph Doherty 92969c9c85 HistorianGateway: Java client 0.2.0 published; follow-ups #119/#120 2026-11-10 09:44:55 -05:00
Joseph Doherty 129d37f9e2 HistorianGateway: Contracts/Client 0.4.0 released (historiangw#79) 2026-11-10 09:39:57 -05:00
Joseph Doherty b9bcf33834 docs(index): HistorianGateway PRs #116/#117 merged (733eb25) 2026-11-10 09:35:54 -05:00
Joseph Doherty a5fd97b013 docs(index): HistorianGateway — ReadBlocks removed, datatype cast-or-reject, event id minting (historiangw 2026-11-10) 2026-11-10 09:35:07 -05:00
Joseph Doherty d430684322 docs(index): OtOpcUa, ScadaBridge, HistorianGateway tips after the 2026-11-10 issue waves
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-10 06:16:05 -05:00
Joseph Doherty 48af177dce fix(theme): shell fills the dynamic viewport — drop calc(100vh - 3.3rem) (scadaproj#10)
.app-shell min-height is now 100vh with a 100dvh override (the 3.3rem was a
donor-app top-bar leftover; ThemeShell has no top bar) and the lg+ sticky
rail is 100vh/100dvh. Source bumped to 0.5.3, UNPUBLISHED. Adds a static
regression test and fixes the CS8602 in NavStateScriptTests (0 warnings).

Browser-checked via Overview on local 0.5.2 vs 0.5.3 packages: at 390x844 a
short page went from a 791px shell (53px gap) to 844px, no extra scroll;
1440x900 rail stays sticky full-height.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 22:36:20 -05:00
Joseph Doherty eab617f741 docs(index): LocalDb 0.3.7 fixes #16; Secrets Replicator.Grpc deprecated (scadaproj#16, #8)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 22:30:57 -05:00
Joseph Doherty ab1ad689df chore(secrets): deprecate Replicator.Grpc — out of the build and pack (scadaproj#8)
Owner chose option (b). ZB.MOM.WW.Secrets.Replicator.Grpc has had no consumer
since ScadaBridge retired the gRPC secrets hub (2026-09-28); OtOpcUa never used it.
- removed the project and its test project from ZB.MOM.WW.Secrets.slnx, so the
  family build/test and build/push.sh's `dotnet pack` skip it;
- csproj IsPackable=false (a direct pack of the project yields nothing);
- SecretsGrpcHubServerExtensions / SecretsGrpcHubClientExtensions [Obsolete];
- README, CHANGELOG (0.6.6 Deprecated), CLAUDE.md and clustered-secrets.md say so.
Source + tests stay in the tree and still build/run standalone (test csproj
suppresses CS0618): 200/200. Feed versions 0.4.1-0.6.3 are left for the owner
to unlist.

Also zeroes the solution's pre-existing warnings: CA1416 on two Unix-only
permission tests (guarded by Skip.IfNot, which the analyzer cannot see — now
[UnsupportedOSPlatform("windows")]) and two xUnit2031 Assert.Single(Where).
Build 0 warnings; tests 429 passed / 21 skipped / 0 failed; pack = 5 nupkgs.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 22:30:57 -05:00
Joseph Doherty be5e9fd436 fix(localdb): keep a tombstone until the peer holds it — no resurrection past TombstoneRetention (scadaproj#16)
0.3.7 (unpublished), owner-chosen option A. A tombstone is now pruned only when
it is past TombstoneRetention AND the peer is known to hold it:
- held while database-wide or per-table snapshot debt is outstanding (the
  snapshot is built from the row-version ledger, so a pruned tombstone is a
  delete it can no longer carry — the issue's second path);
- a local tombstone held while its delete is still in the unacked oplog.
Delivery (delta ack covering the delete, or snapshot debt discharged) restamps
tombstone_utc so retention runs from delivery. New optional
LocalDb:Replication:TombstoneHardCap (default off, >= TombstoneRetention)
bounds an undelivered tombstone's life. No proto, lib_schema_version or
on-disk schema change.

Regression test TombstoneResurrectionTests (two real nodes over loopback gRPC):
offline update on B, newer delete on A, A's clock +8 days (oplog age cap +
tombstone prune) -> reconnect. Fails on 0.3.6 (row resurrected), passes now;
plus a no-prune positive control and a pruned-after-delivery control, and five
controlled-clock OplogStore tests. Each guard clause mutation-killed. 259/259.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 22:27:46 -05:00
Joseph Doherty 3215d51154 docs(auth): record parked constraint-policy + JWT-helper decisions (scadaproj#20)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 22:13:46 -05:00
Joseph Doherty 5c207d1fe5 docs(index): four apps pin Auth 0.4.1 on their default branches (scadaproj#5)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 18:30:57 -05:00
Joseph Doherty 703461dab1 docs(secrets): OtOpcUa is Akka pair-local, never a gRPC-hub consumer; 0.6.3 has no hub consumer left (scadaproj#8)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 18:20:30 -05:00
Joseph Doherty 4382446ebd docs(index): unpublished shared-lib versions after the 2026-11-09 issue waves; Theme 0.5.0 on all consumer default branches
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:53:34 -05:00
Joseph Doherty 3df31d0c7a feat(theme): opt-in ThemeShell ScrollNav rail scroll pane (ScadaBridge#61)
Upstreams ScadaBridge's local .rail-scroll pane. ScrollNav (default false)
wraps Nav in .rail-scroll and adds side-rail-scroll; layout.css (lg+ only)
fills the rail and scrolls just the pane so .rail-foot stays pinned.
Default markup/CSS unchanged for other consumers. Stays at 0.5.2, unpublished.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:52:57 -05:00
Joseph Doherty 6123d03f92 build(overview): bump ZB.MOM.WW.Theme 0.4.1 -> 0.5.0 (scadaproj#9)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:51:24 -05:00
Joseph Doherty ebc493361e fix(secrets): audit malformed ${secret:} tokens, cap SecretName at 450, resolve local UNC shares (scadaproj#52)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:38:36 -05:00
Joseph Doherty 4a3c4e9b7e docs(secrets): record the P3 batch and #49 in findings, CHANGELOG 0.6.6 and the review index (scadaproj#45)
Secrets-004–009, 011, 012, 014–016, 018 and 019 marked Resolved with commit, fix and regression
evidence; Secrets open findings 13 -> 0; code-reviews/README.md regenerated (--check passes).
CHANGELOG 0.6.6 records the fixes, behaviour changes and the #49 follow-ups.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty fc81cbbd36 test(secrets-cli): CLI rig keeps the store outside the working directory (scadaproj#45)
The CLI host takes its working directory as the content root, and the rig put the store under it.
The old lexical store-path rule missed that on macOS only because the temp path is spelled
/var/... while the working directory reports /private/var/...; with Secrets-005's link resolution
the rule (correctly) refused it. The rig now runs from a sibling work/ directory.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty db441d9d99 docs(secrets): document the plain-IConfigurationRoot reload gap and OtOpcUa's redundant starter (scadaproj#49)
The reload gap for a plain IConfigurationRoot is documented rather than fixed: closing it would mean
inserting a provider into ConfigurationRoot's internal list. No family host is exposed (plain roots
are built with reloadOnChange: false; the rest pass a ConfigurationManager). clustered-secrets.md
notes that AddZbSecretsAkkaReplication now starts the actor itself, so OtOpcUa's
SecretReplicationStarter becomes redundant once it adopts 0.6.6.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty fac3c5355c fix(secrets-grpc): hub-call cancellation surfaces as cancellation, not a failed sweep (scadaproj#45)
Secrets-019: the hub channels are created with ThrowOperationCanceledOnCancellation = true, so a
call cancelled through its token throws OperationCanceledException. Defensively, the failover
reader rethrows RpcException(Cancelled)-with-a-cancelled-token as cancellation instead of dialing
every fallback with the same cancelled token, and the sweep treats it as shutdown, not a failure
recorded in ISecretsHubSyncStatus. A server-side Cancelled status (token not cancelled) still fails
over.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty 3aa7c728d5 fix(secrets-cli): bundle import validates every entry before writing (scadaproj#45)
Secrets-018: BundleService.ImportAsync now rehydrates every entry and re-wraps every foreign-KEK
row before the first write, so a malformed or tampered entry anywhere fails the import with the
store untouched ("Nothing was imported"). A store fault during the apply phase (no multi-row
transaction) now reports the row it stopped at and every row already written, which the
interactive flow prints, instead of a bare "Import failed".

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty 649d4a0616 fix(secrets-ui): components re-check their own policy; pin the real policy matrix (scadaproj#45)
Secrets-016: RevealButton (RevealPolicy), SecretEditor and ConfirmDeleteModal (ManagePolicy) now
evaluate their policy through IAuthorizationService at the top of the revealing/mutating handler
and fail closed (no auth state, no IAuthorizationService, or a failed policy), instead of relying
on the host to wrap them in AuthorizeView. New tests build the REAL AddSecretsAuthorization
policies and evaluate each role against each policy, so secrets-manager satisfying RevealPolicy
would now fail a test.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty a84c64e26f fix(secrets-ui): Reveal fails closed when its audit cannot be written (scadaproj#45)
Secrets-015: RevealButton now writes the secret.reveal Success audit before showing the value and
shows nothing ("audit record could not be written") if that write throws; the failure is logged as
a warning with actor and name, never the value. The cancellation token is captured up front, so a
component disposed mid-reveal can no longer turn the audit into a swallowed ObjectDisposedException.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty fe94b32d42 fix(secrets-ui): Add refuses an existing name; restoring a tombstone needs a second submit (scadaproj#45)
Secrets-014: SecretEditor in add mode reads the name first. A live row is refused ("already
exists. Use Rotate") with no write and no audit, so a pasted name can no longer replace a live
credential and reset its description/content type under a "secret.add" audit. A tombstoned name is
restored only when the operator submits the same name a second time after the warning.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty 849640f467 fix(secrets-akka): announce from the mailbox with a sender; chunk anti-entropy payloads (scadaproj#45)
Secrets-011: HandleAnnounceTick pipes the manifest read back to the actor and publishes the
announce from the mailbox with Self as sender. Under a genuinely async store it used to publish
from a pool continuation with NoSender, so every peer replied to deadLetters; a faulted manifest
read was dropped silently and is now logged.

Secrets-012: the exchange's push rows, the pull reply and the pull request are split into
messages of at most 64 KB (measured with the wire encoding), half Akka.Remote's default 128000-byte
frame, so a cold node converges against a large store. A single over-budget row is still sent
alone; the manifest announce is not split (documented in clustered-secrets.md).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty 5e2d3dd1bc fix(secrets): malformed ${secret:} references fail closed; README sample validates (scadaproj#45)
Secrets-009: SecretReferenceExpander.ExpandAsync throws FormatException when a value holds a
${secret: marker that is not a complete reference with a non-blank name (${secret:}, an
unterminated ${secret:name, a nested marker), instead of passing the literal text through as the
credential. ExpandConfigurationAsync names the offending key (never the value) and writes nothing.
The README wiring sample drops the relative "SqlitePath": "secrets.db" (which failed validation)
for the per-user default and shows an absolute example; a test validates the sample.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty 262e11feaf fix(secrets-cli): shipped appsettings.json no longer sets a relative SqlitePath (scadaproj#49)
The CLI's own appsettings.json set "SqlitePath": "secrets.db", which the store-path validator
rejects as relative, so the headless CLI failed at startup when run from its own directory unless
Secrets__SqlitePath overrode it. The key is removed: the per-user default
(<LocalApplicationData>/ZB.MOM.WW/secrets.db) applies, and an app's appsettings.json in the working
directory or the environment still override it. Regression test validates the shipped file.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty 64efb49996 fix(secrets): hub push sweep isolates each row (scadaproj#45)
Secrets-008: SqlServerSecretSyncService.SweepAsync now catches a per-row push failure, logs it
(EventId 4, name only) and continues, like the pull side. One row the hub refuses (a >450-char
name, an over-long explicit KEK id) no longer stops every later name from reaching the hub.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty 16fac72858 fix(secrets): resolver never re-caches across Invalidate; expired plaintext is evicted (scadaproj#45)
Secrets-006: DefaultSecretResolver keeps a per-key invalidation generation; Invalidate bumps it
before evicting, and a resolve that read the store under an older generation withdraws its insert,
so a rotation mid-resolve is not undone for another TTL. Expired entries are removed on lookup and
by a periodic TimeProvider sweep (every TTL, at least 1 s); a non-positive TTL caches nothing.
The resolver is now IDisposable (stops the sweep timer).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty eff8c6a00e fix(secrets): store-path rules compare locations, not spellings (scadaproj#45)
Secrets-005: AddIfNotRooted now uses Path.IsPathFullyQualified, so Windows drive-relative
(C:secrets.db) and root-relative (\secrets.db) paths are rejected. AddIfUnderContentRoot refuses a
store if EITHER its spelled location (device prefix stripped, loopback admin share mapped to its
drive) OR its resolved location (symlinks/junctions followed, 8.3 names expanded on Windows) is
under the likewise-resolved content root. A store spelled through the content root stays refused
even if a link inside carries it elsewhere. UNC paths through other shares are compared as written.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty b64628de0b fix(secrets): malformed rows fail as SecretDecryptionException; one KEK snapshot per cipher op (scadaproj#45)
Secrets-004: AesGcmEnvelopeCipher.Decrypt now wraps the ArgumentException AesGcm throws for a
wrong-length nonce/tag/wrapped DEK as SecretDecryptionException (as Rewrap already did), so the
resolver's decryption-failed audit fires.

Secrets-007: new MasterKeySnapshot (key + KekId from one reading, zeroed on Dispose) and a
default-implemented IMasterKeyProvider.GetSnapshot(); MasterKeyProviderBase overrides it to
resolve the source once and derive the id from that same key. Encrypt/Decrypt/Rewrap take one
snapshot per KEK and dispose it, so a key file swapped mid-operation can no longer stamp a row
with one key's id and wrap it under another. Intermediate key buffers are zeroed. On-disk format
unchanged: a golden row written by the 0.6.5 cipher still decrypts.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:32:28 -05:00
Joseph Doherty b33f0f93c9 fix(auth): SQL Server key store refuses truncation and matches key ids exactly (Auth-008)
- Over-length key records (key_id > 64, prefix > 16, display name > 256) are
  refused with ArgumentException before connecting; an over-64 key-id lookup
  or mutation answers not-found without querying (SqlClient silently
  truncated the sized parameter, so a different id sharing the first 64
  characters matched).
- Every key_id predicate adds an exact VARBINARY comparison, so lookups are
  case- and trailing-space-exact like SQLite; the PK seek is unchanged and
  there is no schema change.
- SqliteApiKeyStoreImporter reports case-only key-id collisions and
  over-length rows in new init lists (KeyIdCollisions, KeysRejected) instead
  of counting them as skips or importing them truncated.
- Audit text truncation kept deliberately and documented.

Offline refused-port tests and live SQL Server 2022 tests fail pre-fix;
SqlServer suite 101/101 live. Auth findings now 0 open; CLAUDE.md records
the #46/#50 work; code-reviews/README.md regenerated.

(scadaproj#46)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:26:03 -05:00
Joseph Doherty c4366539ca fix(auth): ApiKeyVerifier reports store faults as StoreUnavailable (Auth-010)
A key-store lookup that threw (shared SQL Server unreachable, SQLite I/O
fault) escaped VerifyAsync despite the "only exception path is cancellation"
contract, surfacing as an unaudited 500 / gRPC Unknown. ApiKeyFailure gains
StoreUnavailable (appended; numeric values unchanged) and the lookup maps any
non-cancellation exception to it. Unit theory and an offline refused-port
SqlServerApiKeyStore test fail pre-fix.

(scadaproj#46)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:21:00 -05:00
Joseph Doherty b8d3fa2ba1 fix(auth): prove the AD domain of a u:DOMAIN\name user bind
Auth-007's sAMAccountName match assumed the search base covers one AD
domain; across a forest (Global Catalog) it could accept another domain's
same-named account and return its groups. For a u:DOMAIN\name Who-am-I
answer the entry must now also be that domain's account: AD's
msDS-PrincipalName (objectSid-derived DOMAIN\name, read by a base search
through the new ILdapConnection.Read) must equal the answer where offered;
otherwise the name must have exactly one holder under SearchBase and it must
be the entry found. Three forest cases fail pre-fix; single-domain and
sAMAccountName-search compat cases pass both ways. README notes this and
Auth-009.

(scadaproj#50)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:18:46 -05:00
Joseph Doherty 9ec0da1b2c fix(auth): canonical username is the attribute value the user matched (Auth-009)
ExtractUserName returned the first value of a possibly multi-valued
UserNameAttribute (default cn), so jsmith could sign in as "John Smith"
depending on server ordering. It now prefers the value equal to the typed
name ignoring case (still canonicalising case) and falls back to the first
value only when none matches.

(scadaproj#46)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:18:25 -05:00
Joseph Doherty b9a096c53a docs(localdb): refresh README, record 0.3.6 #46/#50 notes (LocalDb-007)
README: 0.3.6 version heading and changelog entries (0.3.5, 0.3.6), OtOpcUa
Phases 1+2, Synchronous EXTRA, per-table baseline wording in Ops notes, test
count 249. CLAUDE.md records LocalDb-005/006/007 and the #50 items, with the
cross-repo LocalDbSyncAuthInterceptor decision left as a note. LocalDb
findings now 0 open; code-reviews/README.md regenerated.

(scadaproj#46)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:13:24 -05:00
Joseph Doherty b2adddbc8e fix(localdb): count snapshot dead-letters and cap held-back snapshot rows
- SnapshotApplier now takes LocalDbMetrics (wired by SyncSessionFactory) and
  adds every row it dead-letters - poison, drift reject, FK orphan, retry
  failure, cap spill - to localdb.sync.dead_lettered. Before, only the delta
  path recorded the metric.
- New ReplicationOptions.MaxSnapshotDeferredRows (default 100,000, validated
  > 0) bounds the rows held for a missing FK parent; past it the oldest get
  one more apply with deferral off and are dead-lettered if still orphaned.
  An older name-ordered sender could otherwise defer a whole child table.

Unit + 2-node (SyncSessionFactory) tests fail pre-fix. No wire change.

(scadaproj#50)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:12:41 -05:00
Joseph Doherty fd46999946 fix(localdb): refuse AUTOINCREMENT keys at RegisterReplicated (LocalDb-005)
Each node assigns its own AUTOINCREMENT keys, so two different rows inserted
on the two nodes share a pk_json and LWW silently keeps one on both nodes.
RegisterReplicated now refuses such a table (detected from SQLite column
metadata, before any trigger is installed). A plain INTEGER PRIMARY KEY is
still accepted (application-assigned ids are legitimate); the requirement
that replicated keys be unique across both nodes is documented in the
RegisterReplicated remarks and README Limitations. No ScadaBridge or OtOpcUa
replicated table is AUTOINCREMENT.

(scadaproj#46)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:09:45 -05:00
Joseph Doherty 76e9c355b4 fix(localdb): escape apostrophes in apply/snapshot JSON paths (LocalDb-006)
A column name containing ' was captured fine but ended the JSON-path SQL
literal early on the apply and snapshot paths, dead-lettering every row of the
table on the peer and faulting the snapshot page query for a quoted PK column.
Both paths now share JsonPathSql.For, which doubles ' after the JSON-path
escape. 2-node delta and wiped-peer snapshot tests fail pre-fix.

(scadaproj#46)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:08:04 -05:00
Joseph Doherty c207573595 fix(localdb): FailClosedOnDrift applies to snapshot rows (scadaproj#39)
The drift guard lived only in the delta path; SnapshotApplier applied every
row unchecked, so a future-stamped snapshot row was applied, observed by the
clock and persisted as last_seen_hlc - moving the receiver's HLC ahead across
restarts despite FailClosedOnDrift (LocalDb-004). SnapshotApplier now takes
ReplicationOptions and runs the same per-row check (warn once per snapshot;
dead-letter under FailClosedOnDrift via the shared HlcDriftGuard, with the
row's HLC kept out of last_seen_hlc).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:02:17 -05:00
Joseph Doherty 15a6c7c710 fix(localdb): apply upserts on the primary key, not INSERT OR REPLACE (scadaproj#38)
INSERT OR REPLACE resolved a secondary UNIQUE conflict by deleting a
different row (another PK) with capture suppressed and its ledger left live,
so a pair diverged silently (LocalDb-003). The applier now uses
INSERT ... ON CONFLICT(<pk>) DO UPDATE (DO NOTHING when every column is PK):
a clash on another unique key aborts the entry, which is dead-lettered, and
each node keeps its own row. Side effect: a remote update of a parent with
ON DELETE RESTRICT children now applies instead of being dead-lettered.

Also waits for the snapshot watermark in WipedPeer_SnapshotLiftsItsWatermark,
which raced SnapshotComplete under full-suite load.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:02:17 -05:00
Joseph Doherty 4af0ea8152 fix(localdb): snapshot delivers FK-linked rows in any order (scadaproj#37)
The snapshot streamed tables by name and rows by pk_json text, so a child
(or a self-reference whose parent's key sorts later) reached the receiver
first, failed its immediate FK check and was dead-lettered - permanently,
since the snapshot's watermark and ack covered it (LocalDb-002).

Sender: stream referenced tables first (Kahn order, name tie-break).
Receiver: SnapshotApplier defers rows that fail only
SQLITE_CONSTRAINT_FOREIGNKEY, retries them as rows land, and dead-letters
true orphans at SnapshotComplete. Delta path unchanged; wire unchanged.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:02:17 -05:00
Joseph Doherty 48813bba6f fix(localdb): sync endpoint enforces the configured ApiKey (scadaproj#36)
LocalDbSyncService never read request headers, so setting
LocalDb:Replication:ApiKey on both nodes left the passive endpoint open
(LocalDb-001). It now requires Authorization: Bearer <key> (constant-time)
before the handshake and before newest-wins takeover, refusing anything else
with Unauthenticated. A blank key keeps the old accept-all behaviour and
logs a startup warning. Wire-compatible: the initiator has always sent the
header when the key is set; ScadaBridge/OtOpcUa interceptors use the same key.

LocalDb 0.3.5 -> 0.3.6 (unpublished).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:02:16 -05:00
Joseph Doherty d549a782fd fix(auth): user bind proves the bound account is the entry whose groups it returns (scadaproj#40)
BindMode=User bound as UserBindTemplate({0}) and then returned the groups of
whatever entry (UserNameAttribute={0}) found - two directory lookups that can
name two accounts (Auth-007). Reproduced live against GLAuth: mallory bound as
herself and signed in with boss's Admins group.

After the bind the service now asks RFC 4532 Who-am-I and requires the entry
to be that account (dn: -> DN match; AD u:DOMAIN\name -> sAMAccountName match).
Without a Who-am-I answer only a DN template is provable (bind DN must equal
the entry DN); anything else fails closed as GroupLookupFailed. {0} is
RFC 4514-escaped in DN templates; validator message leads with EXAMPLE\{0}.

Auth 0.4.3 -> 0.4.4 (unpublished).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:02:16 -05:00
Joseph Doherty 5f5d684c44 fix(secrets): CLI set/rotate read the value from stdin or a masked prompt (scadaproj#35)
`secret set`/`rotate` took the plaintext as a positional argument (shell
history, process list), and Program handed argv to
Host.CreateApplicationBuilder, whose command-line config provider crashed on
a value like "-p=Hunter2Secret" with the value in the unhandled
FormatException on stderr.

- SetCommandLine: `set|rotate <name> [-|--value-stdin]`; no value reads piped
  stdin or prompts twice (masked) at a TTY; one trailing newline dropped;
  empty refused. The positional <value> still works and warns on stderr.
- host built from HostApplicationBuilderSettings without argv; startup
  failures print `secret: startup failed: <msg>` and exit 1
- unexpected trailing arguments reported by position, not echoed
- tests: SetCommandLineTests incl. two child-process runs of the built CLI;
  the -p=Hunter2Secret probe fails (leaks) on the old Program.cs
- docs: README, clustered-secrets runbook, CHANGELOG
- code-reviews: Secrets-017 Resolved; README regenerated

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:00:06 -05:00
Joseph Doherty e1487fbf10 fix(secrets): UI reports a committed change as saved when its audit throws (scadaproj#34)
SecretEditor and ConfirmDeleteModal wrote the success audit inside the same
try as the store write, so a throwing IAuditWriter after a committed
add/rotate/delete showed an error, wrote a Failure audit and skipped the
resolver-cache eviction - the old plaintext kept resolving for the TTL.

The mutation try now covers only the cipher + store call; the success audit
is best-effort afterwards and logs a warning (no value) on failure, so the
change is reported saved, the callback fires and the cache is evicted.

- tests: AuditFailureAfterCommitTests (add, rotate, delete) with a throwing
  success audit; all fail without the fix
- code-reviews: Secrets-013 Resolved; README regenerated

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:00:06 -05:00
Joseph Doherty 6112a9f447 fix(secrets): Akka replication actor starts with the host (scadaproj#33)
The replication actor was created only when something resolved ISecretStore
(store -> replicator -> SecretReplicationActorProvider.ActorRef). A node that
expanded its ${secret:} references pre-host and never touched the store at
runtime had no actor: no topic subscription, no announces, no pull replies.

AddZbSecretsAkkaReplication now registers SecretReplicationActorStarter, which
creates the actor on IHostApplicationLifetime.ApplicationStarted (after every
hosted service, incl. an Akka.Hosting AkkaHostedService registered later), or
in StartAsync when no lifetime is registered.

- tests: EagerActorStartTests (generic host in both registration orders with a
  no-actor-before-start control; bare container) - all fail without the fix
- docs: README, CHANGELOG
- code-reviews: Secrets-010 Resolved; README regenerated

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:00:06 -05:00
Joseph Doherty f60f641069 fix(secrets): ${secret:} expansion survives configuration reload (scadaproj#32)
ExpandConfigurationAsync wrote through config[key] = ..., which only sets the
providers' in-memory Data; a file provider's reload replaces it, so editing
appsettings.json on a running service reverted every expanded key to its
${secret:...} placeholder.

- ConfigurationManager: expanded values are pinned in an internal overlay
  source appended last; its provider's Load() is a no-op and Build always
  returns the same provider, so reloads (and source rebuilds) keep the pins
- any other IConfigurationRoot: in-place write as before, re-applied from the
  root's reload token
- all references resolve before anything is written (a fail-closed miss no
  longer leaves the config half expanded)
- tests: SecretExpansionReloadTests (real JSON file + Reload(), options
  monitor, plain root); three fail without the fix
- docs: README reload note, CHANGELOG
- code-reviews: Secrets-003 Resolved; README regenerated

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:00:06 -05:00
Joseph Doherty c3b07d6766 fix(secrets): SqlServer/Akka extensions take contentRootPath; last explicit root wins (scadaproj#31)
The SQL-Server extensions called the 3-arg AddZbSecrets, and the store-path
validator captured the content root of whichever call registered it first.
In hub mode no registration order applied the pre-host under-content-root
guard: extension-first dropped the app's 4-arg root, core-first lost the
replicator (#30). That is the 0.6.0 store-path hole, reopened.

- AddZbSecretsSqlServerStore / AddZbSecretsSqlServerReplication /
  AddZbSecretsAkkaReplication gain a trailing optional contentRootPath,
  forwarded to the 4-arg AddZbSecrets
- the root now lives in one SecretsContentRoot instance holder per service
  collection; the last explicit root wins, null never erases one; the
  IHostEnvironment fallback is unchanged
- tests: ContentRootTests (hub mode, three compositions, artifact asserted
  before the throw, positive control), last-explicit-wins theory in
  SecretsStorePathRulesTests, Akka forwarding test
- code-reviews: Secrets-002 Resolved; README regenerated

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:00:06 -05:00
Joseph Doherty 015c556ced fix(secrets): SqlServer/Akka registration is order-independent; bump 0.6.6 (scadaproj#30)
AddZbSecretsSqlServerStore / AddZbSecretsSqlServerReplication (and the Akka
extension, same defect class) TryAdd-ed their ISecretStore, ISecretsStoreMigrator
and ISecretReplicator ahead of their internal AddZbSecrets call. An application
that had already called AddZbSecrets therefore silently kept the SQLite store
(shared-store mode) or NoOpSecretReplicator (hub/Akka modes).

They now call AddZbSecrets first and RemoveAll + AddSingleton their own
registrations; a later AddZbSecrets only TryAdds, so either order yields the
same graph with exactly one ISecretStore registration.

- tests: RegistrationOrderTests (SqlServer + Akka) build and resolve the real
  container in both orders; core-first fails without the fix
- Directory.Build.props 0.6.5 -> 0.6.6 (NOT packed or published)
- code-reviews: Secrets-001 Resolved; README regenerated

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:00:05 -05:00
Joseph Doherty 1786bab0a0 fix(telemetry): redact after ConfigureLogger enrichers, keep colliding dictionary keys, require http(s) OTLP endpoint and validate the options overload; bump 0.2.1 (scadaproj#48)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:57:48 -05:00
Joseph Doherty 5bf2f2caf1 fix(theme): nav-state.js tracks wired sections in a WeakSet so enhanced navigation cannot stack toggle listeners; bump 0.5.2 (scadaproj#48)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:56:33 -05:00
Joseph Doherty ab3fa9ca83 fix(health): AkkaActiveNodeGate.ForOptions shares the probe's RolePreference scope; bump 0.3.1 (scadaproj#48)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:55:45 -05:00
Joseph Doherty 3ef43ca926 fix(overview): P3 review fixes 003-005 - no redirects on probes, per-target publish so a hung instance cannot stale the rest, probe docs (scadaproj#48)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:54:12 -05:00
Joseph Doherty 362ba8d75f fix(galaxyrepository): P3 review fixes 003-008 - cycle re-rooting, scaled stale threshold, notifier ordering, DI tests, Pkcs 9.0.21 pin, snapshot docs; bump 0.2.2 (scadaproj#47)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:52:00 -05:00
Joseph Doherty 90b691af84 docs(deployment): correct the QA leader-resolution note after scadaproj#43
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:48:49 -05:00
Joseph Doherty 414050935e fix(galaxyrepository): scoped browse surfaces ancestors as navigation-only nodes (scadaproj#42)
A browse-subtree scope such as Plant/LineA/* filtered out Plant and
Plant/LineA, so scoped lazy browse from the root was empty and
DiscoverHierarchy returned orphans. Out-of-scope ancestors of an allowed
object are now returned as navigation-only containers: attributes stripped,
child_has_children = true, and only their children on the path to an allowed
object are listed (siblings stay hidden). DiscoverHierarchy reports them in
GalaxyHierarchyQueryResult.NavigationAncestorCount; WatchDeployEvents
subtracts it so its scoped counts stay allowed-objects-only.

- tests: ScopedAncestorBrowseTests; deploy-event scope test updated
- IGalaxyBrowseScopeProvider documents the semantics; CLAUDE.md 0.2.1 notes
- code-reviews: GalaxyRepository-002 Resolved; README regenerated

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:48:02 -05:00
Joseph Doherty 20cf3bfec7 fix(galaxyrepository): cap the per-entry filter memo at 64 signatures; bump 0.2.1 (scadaproj#41)
Both projectors memoized one full result list per filter signature with no
limit, and the signature is client-controlled (tag_name_glob '*', '**', ...),
so distinct globs retained memory until the next Galaxy deploy. A bounded FIFO
ProjectionMemo<T> now backs both memos; an evicted signature is recomputed.

- tests: ProjectionMemoBoundTests (500 distinct globs per projector, re-query
  after eviction)
- Directory.Build.props 0.2.0 -> 0.2.1 (NOT packed or published)
- code-reviews: GalaxyRepository-001 Resolved; README regenerated

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:45:32 -05:00
Joseph Doherty a2e2f4b463 fix(theme): TechButton honours a caller-supplied disabled; bump 0.5.1 (scadaproj#44)
The trailing disabled="@Busy" overrode the splatted attribute, so a caller's
disabled was dropped whenever Busy was false and the button stayed clickable.
The effective state is now Busy || caller disabled (Blazor splat semantics).

- tests: caller disabled (true/"disabled"/""), false, and re-render toggle
- Directory.Build.props 0.5.0 -> 0.5.1 (NOT packed or published)
- code-reviews: Theme-007 Resolved; README regenerated

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:44:14 -05:00
Joseph Doherty 6c81c0bc0a fix(overview): resolve a group's leader against its own members (scadaproj#43)
LeaderResolver searched every instance of the application, so co-located
groups (QA: ScadaBridge central-a and site-a both on vq03) got the
first-listed group's instance name on their leader chip. Resolution is now
scoped to the group's members; an unmatched address keeps its raw form.

- tests: QA co-located central/site layout; cross-group host not borrowed
- CLAUDE.md: correct the leader-resolution / 127.0.0.1 guidance
- code-reviews: Overview-002 Resolved; README regenerated

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:43:18 -05:00
Joseph Doherty c25acd6093 fix(overview): one bad health response no longer stops the dashboard host (scadaproj#29)
ZbHealthReportClient caught only HttpRequestException/OperationCanceledException,
so an unknown Content-Type charset (InvalidOperationException from
ReadAsStringAsync) escaped the probe, faulted Task.WhenAll and the poller
BackgroundService, and StopHost took the dashboard down.

- client: final catch-all returns an Unreachable result for that instance
- poller: per-target Guarded probe + catch-and-log per sweep in ExecuteAsync
- tests: unknown charset (both tiers), arbitrary handler exception, sweep with
  one bad instance, and the BackgroundService survival loop
- code-reviews: Overview-001 Resolved; README regenerated

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:42:23 -05:00
Joseph Doherty 477245f5db docs(code-reviews): review Secrets, LocalDb, GalaxyRepository, Overview; re-review changed libs (scadaproj#15)
First reviews of Secrets, LocalDb, GalaxyRepository and Overview, and
2026-11-09 re-reviews of Auth, Health, Theme, Telemetry, Audit and
Configuration, all at 91fb2b4. 49 new open findings, each with a P1/P2/P3
priority and a failure scenario: 1 P1, 13 P2, 35 P3. README regenerated;
REVIEW-PROCESS, template and regen script now cover all ten libraries and
the Priority field.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:33:14 -05:00
Joseph Doherty 91fb2b48dd docs(health): GrpcDependencyHealthCheck has no consumers - keep it, correct SPEC/README (scadaproj#28)
SPEC 2.4 named OtOpcUa and MxGateway as users; neither is (verified against every
app's default branch; MxGateway worker IPC is named pipes, OtOpcUa deliberately
does not gate readiness on gateway channels). Keep the check (removal is a breaking
API change; small, tested building block), mark it as no-current-consumers in SPEC
2.4/6/7, both READMEs, the shared-contract doc and GAPS.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:19:09 -05:00
Joseph Doherty 726fbccf54 test(secrets): fix Windows failures - skippable permission tests, release SQLite pools before delete (scadaproj#27)
The two Unix-permission tests called Skip.IfNot from a plain [Fact] (xunit v2 +
Xunit.SkippableFact) so they failed on Windows; now [SkippableFact].
Resolver_Works_EndToEnd_ThroughDi calls SqliteConnection.ClearAllPools() before
deleting its temp DB.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:17:11 -05:00
Joseph Doherty 1baa384cbe fix(deps): Microsoft.Data.Sqlite 10.0.7 -> 10.0.13 in Secrets, LocalDb, Auth (scadaproj#26)
10.0.7's pool can hand one handle to two users (efcore#39009). 10.0.13 floors
SQLitePCLRaw 2.1.13, so the transitive lib.e_sqlite3 pin moves 2.1.12 -> 2.1.13
(the old pin is a NU1109 downgrade error). NuGetAudit clean; all suites green.
Versions bumped, NOT published: Secrets 0.6.5, LocalDb 0.3.5, Auth 0.4.3.
GalaxyRepository and Overview do not use Microsoft.Data.Sqlite.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:17:11 -05:00
Joseph Doherty 2fea619da3 docs(health): historiangw#87 fixed on main 5de3dd9 (not yet deployed)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:09:39 -05:00
Joseph Doherty 9cbe65c844 docs(health): re-verify per-app probe coverage against the SPEC; refresh GAPS and current-state (scadaproj#11)
Audited the registration and mapping code of each app at its origin default branch: OtOpcUa
c904472a, MxAccessGateway de86f8b8, ScadaBridge c7d868c5, HistorianGateway 4d6a9ad (all on Health
0.3.0, all MapZbHealth with default paths: /healthz runs nothing, /health/ready and /health/active
by tag). GAPS.md now carries the verified per-endpoint coverage matrix and a SPEC-by-app table;
each current-state doc lists exactly what each endpoint runs, and HistorianGateway gets its first
current-state doc.

Recorded: mxaccessgw#206 (worker-executable + galaxy-sql readiness checks, on /health/ready) is
merged; historiangw#87 (session-pool check latches 503 until restart) is still open at 4d6a9ad.
Deferred P2 downstream probes are now per-app; ScadaBridge IActiveNodeGate unification stays
deferred (shared rule already used, only the interface is local).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:00:44 -05:00
Joseph Doherty f21f2e551d fix(secrets): make concurrent SQLite store initialisation safe; bump to 0.6.4 (unpublished) (scadaproj#25)
Several setups migrating one SQLite secret store at once (mxaccessgw's parallel test hosts on the
per-process store) failed intermittently on Windows with "cannot start a transaction within a
transaction" from SqliteSecretsStoreMigrator.MigrateAsync. That message means the BEGIN ran on a
handle that was already in a transaction: the pinned Microsoft.Data.Sqlite 10.0.7 can hand one
pooled handle to two owners (dotnet/efcore#39009, fixed in 10.0.13) and no 10.0.x refuses to
re-pool a handle whose rollback failed (dotnet/efcore#39082).

The migrator now serialises migrations of one store per process behind a gate keyed on the
normalised path, runs each attempt on a dedicated unpooled connection inside BEGIN IMMEDIATE, and
retries SQLITE_BUSY/SQLITE_LOCKED (another process past the busy timeout) with equal-jitter
exponential backoff. Store operations and the Microsoft.Data.Sqlite pin are unchanged.

Tests: concurrent-init (16 hosts x 20 rounds on fresh and existing stores, two path spellings,
16 AddZbSecrets containers running the pre-host migrator + hosted service), gate sharing/waiting,
BUSY retry past the 5 s busy timeout, transient-code classification.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:57:53 -05:00
Joseph Doherty 01c6dc1d02 build(libs): point package RepositoryUrl/PackageProjectUrl at scadaproj (the zb-mom-ww-* repos do not exist)
All 22 package projects named gitea.dohertylan.com/dohertj2/zb-mom-ww-<lib>,
which return 404; the libraries live as plain directories in scadaproj.
Takes effect on each library's next published version.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:42:29 -05:00
Joseph Doherty b4c38d0f0c docs(libs): refresh stale adoption-status text in hosted library docs (scadaproj#17)
Verified 2026-11-09 against each app's origin default branch pins
(OtOpcUa origin/master c904472a, mxaccessgw origin/main de86f8b8,
ScadaBridge origin/main 7153a197, HistorianGateway origin/main 4d6a9ad)
and the Gitea NuGet feed:
- Audit README: consumer matrix no longer says "adoption deferred" (all four
  apps pin 0.1.0, DEEP-adopted 2026-06-02; HistorianGateway row added);
  dead ~/Desktop/scadaproj-audit paths fixed.
- Configuration CLAUDE.md: drop "not yet pushed to remotes"; all four pin 0.1.0.
- Telemetry README/CLAUDE.md: all four apps call AddZbTelemetry and pin 0.1.0;
  HistorianGateway added to the consumer matrix.
- Secrets CLAUDE.md: lead now says family 0.6.3 on the feed, all four apps pin
  0.6.2, none pins 0.6.3 or Replicator.Grpc.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:40:30 -05:00
Joseph Doherty 1ab5ca026b feat(telemetry): AddZbSerilog minimum-level governance hook; bump to 0.2.0 (scadaproj#12)
Adds an additive AddZbSerilog(builder, configure, configureSerilog) overload
taking ZbSerilogOptions:
- MinimumLevelGovernor: Func<IConfiguration, LogEventLevel?> applied with
  MinimumLevel.Is AFTER ReadFrom.Configuration, so an app-owned key (e.g.
  ScadaBridge:Logging:MinimumLevel) outranks Serilog:MinimumLevel; null defers
  to config; Serilog:MinimumLevel:Override:* entries still apply.
- ConfigureLogger: runs last, for app filters/enrichers/sinks (ScadaBridge's
  standby active-node exclusion).

The two-argument overload is unchanged. 8 new tests (4 fail with the hook
neutralized). Telemetry + Telemetry.Serilog 0.1.0 -> 0.2.0, not published.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:39:06 -05:00
Joseph Doherty a05ce8c86d fix(secrets): pin transitive AngleSharp 1.5.0 to clear NU1902 from bunit 1.40.0 (scadaproj#24)
bUnit 2.x drops RenderComponent/AddTestAuthorization, so pin the parser
instead of migrating the Ui tests.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:37:33 -05:00
Joseph Doherty 243c3fa619 feat(auth): typed ApiKeyPepperUnavailableException for missing API-key pepper; bump to 0.4.2 (scadaproj#23)
Derives from InvalidOperationException so existing catches keep working.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:30:04 -05:00
Joseph Doherty 8bb2679e43 fix(secrets,auth): pin patched System.Security.Cryptography.Pkcs 9.0.21 so restore passes NuGetAudit (scadaproj#22)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:28:42 -05:00
Joseph Doherty d0d3058651 fix(secrets): jittered exponential backoff in SqlServerSecretsStoreMigrator + 8-way concurrent-migrate live test
Flat 100*attempt backoff let concurrent boots retry in lockstep (Auth's twin loop
exhausted retries ~1/60 eight-way boots). Backoff is now exponential with equal
jitter, via an injectable Random for deterministic tests.

Refs scadaproj#18
2026-11-09 12:05:33 -05:00
Joseph Doherty a16567b8bf docs(index): HistorianGateway native event reads return rows on gRPC-only main (historiangw#24 closed); SysTimeSec #29 still open 2026-11-09 11:44:33 -05:00
Joseph Doherty 66c3e060ae docs(index): mxaccessgw Contracts/Client 0.3.0 published; main e5e7f18 2026-11-06 16:01:22 -05:00
Joseph Doherty 19d59915ea docs(index): HistorianGateway main now gRPC-only (swap-historian-client merged, 99b4a7d) 2026-11-06 15:52:22 -05:00
Joseph Doherty 6b737b12b1 docs(index): refresh ScadaBridge/HistorianGateway rows; record HG 2026-10-16 diagnostics + Int1 milestones 2026-11-06 15:38:26 -05:00
Joseph Doherty 484d530e65 docs: point remaining Auth/observability GAPS items at issues (#20, ScadaBridge#81) 2026-11-06 15:36:33 -05:00
Joseph Doherty fd180e576f docs: point markdown backlogs at Gitea issues (status lives in Gitea)
Adds the family backlog standard to the root index (open work = Gitea issues,
shared label set, BTDB excluded) and converts components/*/GAPS, hosted-lib
CLAUDE.md notes, code-reviews, infra/glauth and plan docs to banner + issue
pointers (scadaproj #5-#19, ScadaBridge#79).
2026-11-06 15:34:30 -05:00
Joseph Doherty 967da5b43b feat(theme): upstream router controls and responsive shell fixes 2026-11-04 00:52:25 -05:00
Joseph Doherty 6ad15fcf93 Index: record mxaccessgw operator-authenticated alarm ack (proto change)
Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT
2026-10-20 08:52:46 -04:00
Joseph Doherty 795af1da71 Record merged-main verification and remaining issue gates 2026-10-13 22:10:40 -04:00
Joseph Doherty 65c6b99cf2 Record verified driver fixture cleanup merge 2026-10-13 21:08:01 -04:00
Joseph Doherty 420c2e0783 Record verified freshness merge and pending cleanup follow-ups 2026-10-13 19:04:46 -04:00
Joseph Doherty 3cacdca861 Record verified ServiceLevel fixes and freshness follow-up 2026-10-13 16:00:45 -04:00
Joseph Doherty ade49c0935 Record verified OPC UA CI closures and pending ServiceLevel work 2026-10-13 13:58:03 -04:00
Joseph Doherty 02480d4fbc docs: record verified OPC UA CI and S7 evidence corrections 2026-10-13 11:57:35 -04:00
Joseph Doherty 87bb647efb Record verified keepalive survival test fix 2026-10-13 11:02:00 -04:00
Joseph Doherty a0cec479b6 Record explicit live-test gates and CI follow-ups 2026-10-13 10:37:45 -04:00
Joseph Doherty 91baba8fcc Record verified corrected Gateway rollout 2026-10-13 10:15:45 -04:00
Joseph Doherty 9688707d82 Record gateway correction and reset-echo verification 2026-10-13 10:02:44 -04:00
Joseph Doherty 509114360d Record failed Gateway event-read rollout and rollback evidence 2026-10-13 09:43:48 -04:00
Joseph Doherty cfd371ce18 Record OtOpcUa documentation merge and CI follow-up evidence 2026-10-13 09:16:31 -04:00
Joseph Doherty 51a956a878 Record verified event route and ScadaBridge issue closures 2026-10-13 08:58:15 -04:00
Joseph Doherty 2a3baae301 Record verified SQL event fault fix and route probe limits 2026-10-13 08:18:12 -04:00
Joseph Doherty 10fc22b87e Record Gateway read cancellation fix and event probe evidence 2026-10-13 07:29:35 -04:00
Joseph Doherty 8825cd966f docs(index): record durable alarm identity fix 2026-10-13 07:12:19 -04:00
Joseph Doherty 69a7f8e1b5 docs(index): record historian cleanup status fix 2026-10-13 06:56:02 -04:00
Joseph Doherty 01a6313fe7 docs: record verified restart wire test fix 2026-10-13 06:30:59 -04:00
Joseph Doherty e7cfa21fda docs: record verified local Gateway metadata rollout 2026-10-13 06:19:29 -04:00
Joseph Doherty 68f1b56acf docs: record Docker auth correction and reconnect reproduction 2026-10-13 05:43:43 -04:00
Joseph Doherty b4da0deacb docs: record aggregate and catalog fixes and verification gates 2026-10-13 05:31:38 -04:00
Joseph Doherty 180403cb17 docs: record verified OtOpcUa cache coverage merge 2026-10-13 05:29:45 -04:00
Joseph Doherty 67c182ce18 docs: record gateway catalog and key follow-up merge 2026-10-13 05:06:02 -04:00
Joseph Doherty 05042e5e36 docs: record historian merge and pending verification issues 2026-10-13 04:49:11 -04:00
Joseph Doherty aed5fbf046 docs(index): record missing-tag and gateway discovery fixes 2026-10-13 04:33:36 -04:00
Joseph Doherty 00ef22823f docs(index): record OtOpcUa historian fixes and live measurement 2026-10-13 03:51:45 -04:00
Joseph Doherty c05a6d93b0 docs(index): OtOpcUa #692–#694 historian paging/AtTime/ceiling batch 2026-10-13 02:12:30 -04:00
Joseph Doherty ec2615a9d2 docs(history): OtOpcUa #689–#691 reverse walk sizing, ReturnBounds, gateway ceiling/events 2026-10-13 00:11:34 -04:00
Joseph Doherty 2a0b34e056 docs(history): OtOpcUa #685–#688 Gateway historian raw/aggregate fixes 2026-10-12 16:04:02 -04:00
Joseph Doherty 4555a3bdad docs(index): OtOpcUa live AVEVA gate — #675/#677/#679/#681 closed, historiangw#27 + #685–#688 filed 2026-10-12 14:21:18 -04:00
Joseph Doherty 681606dad0 docs(index): OtOpcUa batch #681–#684 — Gateway per-sample from raw, advertised aggregates, QuestDB tag index, Good-only aggregates 2026-10-12 13:59:34 -04:00
Joseph Doherty aa7093b53b docs(index): OtOpcUa batch #679–#680 — historian aggregate parity, Gateway Average/Count refused 2026-10-12 08:38:50 -04:00
Joseph Doherty 17cb91a315 docs(index): OtOpcUa follow-up batch #674-#678 (fast OpcUaClient recovery, reverse history reads, HistoryUpdate Primary-only, role overlays) 2026-10-11 13:20:46 -04:00
Joseph Doherty 0adfb244b2 docs(index): OtOpcUa batch #667-#673 (retention, Part 11 modified values, event CPs, OpcUaClient session loss, time-weighted aggregates, unreachable-Primary capture) 2026-10-11 10:18:36 -04:00
Joseph Doherty c6e60cb6c4 docs(index): OtOpcUa pluggable historian (SqlServer #652, QuestDB #666) 2026-10-11 04:42:08 -04:00
Joseph Doherty c713925ac7 docs(index): OtOpcUa #665 dead in-place ApplyDelta seam deleted
Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-09 11:32:54 -04:00
Joseph Doherty 0b056c6fee docs(index): OtOpcUa #664 mid-connect ApplyDelta config adoption
Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-09 11:17:15 -04:00
Joseph Doherty 484b176cd6 docs(index): OtOpcUa #663 in-place ApplyDelta re-subscribes data + alarms
Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-09 08:00:11 -04:00
Joseph Doherty dd1eea2106 docs(index): OtOpcUa #662 native-alarm feed survives non-respawning deploys
Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-09 07:36:04 -04:00
Joseph Doherty 63cc772e8d docs(index): OtOpcUa hw5 batch — #657 alarm restatement, #660, #661, #592 hw evidence, #662 filed 2026-10-09 07:20:35 -04:00
Joseph Doherty 3b4d81e630 docs(index): OtOpcUa hw4 batch #611/#592 history entry
Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-09 04:36:47 -04:00
Joseph Doherty b6f5eb2535 docs(index): OtOpcUa hw3 batch #654-#656 history entry
Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-09 00:19:30 -04:00
Joseph Doherty a8f5f66647 docs(index): OtOpcUa hardware batch #647-#651 + hw2 live gates 2026-10-08 22:03:14 -04:00
Joseph Doherty df21d365ec docs(history): OtOpcUa hardware-available batch #640-#646 (alarm carry-over, honest deploy acks, OpcUaClient/AbCip alarm routing)
Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-08 18:23:34 -04:00
Joseph Doherty a2b40b7922 fix(theme): .rise uses fill-mode backwards so it stops trapping position:fixed descendants (OtOpcUa #643)
Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-08 16:50:08 -04:00
Joseph Doherty 3c91f0f813 docs(history): OtOpcUa issue batch #626-#638 (exact condition severity, MTConnect alarms) 2026-10-08 16:33:45 -04:00
Joseph Doherty a6c4161719 docs(history): OtOpcUa hardware-available issue sweep #593-#625 2026-10-08 09:10:46 -04:00
Joseph Doherty 78ca2a6744 docs(index): OtOpcUa Gitea issue sweep #562-#591 — ScadaBridge-visible ACL/alarm-event changes
Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-08 01:45:05 -04:00
Joseph Doherty 21a95c7f50 docs(history): OtOpcUa native AB transport merged — AbCip native default, AbLegacy opt-in, real-press gate passed 2026-10-07 22:45:47 -04:00
Joseph Doherty c43d7ee1ad docs(history): OtOpcUa AbCip/AbLegacy gain a native managed transport behind a Transport switch 2026-10-07 19:12:40 -04:00
Joseph Doherty d0b66bf105 docs(history): OtOpcUa TwinCAT native array subscriptions (2026-10-07) 2026-10-07 15:09:04 -04:00
Joseph Doherty 44421dc5aa docs(history): OtOpcUa FOCAS/TwinCAT/AbCip driver fixes ported from ignitionoee + real-device gates (2026-10-07) 2026-10-07 14:32:57 -04:00
Joseph Doherty 8fa7631ec4 overview: register BTDB Manager on vd03 (Wonder overlay) and QA; deployment notes 2026-10-01 02:05:44 -04:00
Joseph Doherty b62cfad48d index: BTDB master a81a480 — LDAP sign-in by user bind (Auth 0.4.1) 2026-10-01 01:44:27 -04:00
Joseph Doherty 625f207e08 index: Auth feed carries 0.4.1 2026-10-01 01:31:16 -04:00
Joseph Doherty 29bfa8fbf9 Merge fix/auth-ldap-0.4.1: Auth 0.4.1 (canonical username, empty-password guard in both modes) 2026-10-01 01:31:06 -04:00
Joseph Doherty b0582eb66a release(auth): 0.4.1 — canonical username, empty passwords refused in both modes, template guidance 2026-10-01 01:27:55 -04:00
Joseph Doherty 9090b1b511 docs(auth): prefer the down-level UserBindTemplate; warn on UPN templates (I1) 2026-10-01 01:27:55 -04:00
Joseph Doherty e3d146aa21 fix(auth): canonical username from the entry; refuse empty passwords in both bind modes
- Request UserNameAttribute in the search (de-duplicated, case-insensitive) and return its
  first value as LdapAuthResult.Username, falling back to the typed name (I2).
- The empty-password guard now applies in ServiceAccount mode too: AD treats an empty-password
  simple bind as an unauthenticated bind and reports success (I3).
- Restore the dropped explanatory comments in CompleteWithServiceAccount / SearchUser.
2026-10-01 01:27:27 -04:00
Joseph Doherty 177881c423 Merge feat/auth-ldap-user-bind: Auth 0.4.0 opt-in LDAP user bind 2026-10-01 01:08:53 -04:00
Joseph Doherty 3c42069673 docs(index): 0.4.0 entry placement 2026-10-01 01:02:47 -04:00
Joseph Doherty 00ac436ae2 release(auth): 0.4.0 — opt-in LDAP user bind 2026-10-01 00:58:55 -04:00
Joseph Doherty 302d1245cd feat(auth): LdapAuthService user-bind flow (bind as the user, read own groups on the same connection) 2026-10-01 00:55:04 -04:00
Joseph Doherty fa0ca66a05 feat(auth): normalise DOMAIN\name and name@suffix logins for user bind 2026-10-01 00:48:25 -04:00
Joseph Doherty 711e8beb2b feat(auth): LdapBindMode.User options and validation 2026-10-01 00:47:04 -04:00
Joseph Doherty 9ac6ed51d3 index: ScadaBridge main @ 3a217b94 (stale secret-mirror status rows pruned) 2026-09-29 11:17:52 -04:00
Joseph Doherty efd5d881dc index: Secrets 0.6.3 published; ScadaBridge site-secrets follow-ups (2650f794) 2026-09-28 21:47:04 -04:00
Joseph Doherty 0793159cbb docs(secrets): 0.6.3 changelog entry 2026-09-28 21:25:14 -04:00
Joseph Doherty 51b6f1ab9f index: ScadaBridge site-secrets-on-artifact-deploy merged (23a139a4); Secrets 0.6.3 on main, unpublished 2026-09-28 21:14:16 -04:00
Joseph Doherty 29d0c50f07 index: ScadaBridge secrets via artifact deploy; Secrets 0.6.3 2026-09-28 20:24:16 -04:00
Joseph Doherty adbf2eb182 fix(secrets): synchronize SecretsHubSyncStatus getters under the write lock
Review finding (Fix round 1, Task 1): the property getters read their
backing fields without synchronization while RecordSuccess/RecordFailure
write them under _gate, so a concurrent read could observe a torn
DateTimeOffset or a mix of fields from two different writes. Converted the
four auto-properties to explicit properties over private fields, each
getter taking the same lock the writers use. Public interface unchanged.
2026-09-28 17:30:33 -04:00
Joseph Doherty b392b84f21 feat(secrets): 0.6.3 — hub sweep outcome logging (in-sync debug + hourly heartbeat + recovered) and ISecretsHubSyncStatus
GrpcSecretSyncService's background sweep now records outcomes on a new
SecretsHubSyncStatus (registered singleton, exposed as public
ISecretsHubSyncStatus) and logs three new events on the outcome-recording
path: EventId 4 (Debug, every in-sync sweep), EventId 5 (Information, the
same outcome throttled to at most once per the new
SecretsGrpcHubClientOptions.InSyncLogInterval, default 1h), and EventId 6
(Information, the first sweep to succeed after one or more failures).
EventIds 1-3 are unchanged; the raw internal SweepAsync still throws on
failure exactly as before. Not yet published to the Gitea feed and
ScadaBridge is not re-pinned — that is a separate, later step.
2026-09-28 17:26:25 -04:00
Joseph Doherty 5c73be486d index: ScadaBridge b3021e7c deployed to QA vq03/vq04 (2026-09-28, migrations 57) 2026-09-28 11:12:04 -04:00
Joseph Doherty 308742b7a6 docs: ScadaBridge — main 5cc09b08 (script Files access), DEV vd03 on b3021e7c 2026-09-28 10:46:08 -04:00
Joseph Doherty 8cfe076012 docs: ScadaBridge — DEV vd03 on fe89363b + MES test machines (2026-09-28); row 126 now QA-only 2026-09-28 10:10:21 -04:00
Joseph Doherty 646af887d1 docs: winrm re-enabled for deployment activities only (2026-09-28)
Replaces the 2026-09-11 remote-exec hold: WinRM exec is allowed only for the on-box steps of a
user-requested deploy; ad-hoc diagnostics/version checks use SMB, HTTP or SQL. SMB file copies and
direct SQL logins remain always allowed. Scope rules live in the winrm skill's Scope section.
2026-09-28 09:25:12 -04:00
Joseph Doherty 1e0bfe03d4 docs: HistorianGateway row notes the Java client 2026-09-15 19:31:18 -04:00
Joseph Doherty 9934bea05a docs: ScadaBridge index row — main @ fb54ed42 (register row 126: vd03/vq03/vq04 migration rollout TODO)
Claude-Session: https://claude.ai/code/session_01Y5ef34iUUMjmwnMpL9xgmB
2026-09-14 14:43:33 -04:00
Joseph Doherty d0079ba1a1 docs: ScadaBridge index row — main @ ac833f5a pushed 2026-09-14
Claude-Session: https://claude.ai/code/session_01Y5ef34iUUMjmwnMpL9xgmB
2026-09-14 14:41:37 -04:00
Joseph Doherty 4dda768801 docs: ScadaBridge index row — local main @ 3a21cfc2 (2026-09-14: site artifact staleness, pending-updates indicator, scrollable nav); not pushed
Claude-Session: https://claude.ai/code/session_01Y5ef34iUUMjmwnMpL9xgmB
2026-09-14 14:38:48 -04:00
Joseph Doherty f6eef9d8eb docs: BTDB index row — master @ 695192d (2026-09-11: Manager edits, shows and audits batch transfers; ~198 ahead, unpushed)
Claude-Session: https://claude.ai/code/session_01XuWnsPJZ4XK9qPBBtnuqr2
2026-09-11 13:04:34 -04:00
Joseph Doherty 16a84f9df4 docs: ScadaBridge index row — main pushed @ 9d529b82 (2026-09-11: #36 handshake, MES-reportable alarm flag, Flow Debugger nav); deployed tip unchanged
Claude-Session: https://claude.ai/code/session_01Y5ef34iUUMjmwnMpL9xgmB
2026-09-11 12:30:30 -04:00
Joseph Doherty 3c92bf54b0 docs(btdb): index the DB-6 re-fix — forward loop guard, whole-lot chain walks (5f0da01)
Claude-Session: https://claude.ai/code/session_01XuWnsPJZ4XK9qPBBtnuqr2
2026-09-11 09:44:56 -04:00
Joseph Doherty fb33924473 docs(index): BTDB — dbo.TransferMachineBatch merged on local master; no branch in flight
Claude-Session: https://claude.ai/code/session_01XuWnsPJZ4XK9qPBBtnuqr2
2026-09-11 09:22:47 -04:00
Joseph Doherty 46fa06a612 docs(index): BTDB row + history — Blazor conversion, review remediation and DARS schema all merged on local master; Claude artifacts gitignored in btdb; cut-over blocked by the remote-access hold
Claude-Session: https://claude.ai/code/session_01PpXxRCFznFqE65ay6wAJwe
2026-09-11 09:16:48 -04:00
Joseph Doherty 5ee31dbf7b docs(index): winrm remote exec on the wonder boxes disabled 2026-09-11 (security software); UNC copies + direct SQL still allowed
Claude-Session: https://claude.ai/code/session_01PpXxRCFznFqE65ay6wAJwe
2026-09-11 08:55:08 -04:00
Joseph Doherty 98868a60d0 docs(index): DEV + QA wonder boxes at every repo tip after the 2026-09-10 winrm round
CLAUDE.md: ScadaBridge row records main @ 17864d1a (records only, code tip
2b9a7c3c) deployed on vd03 and the vq03/vq04 pair; Theme/Auth/LocalDb rows
lose their "not yet deployed" caveats (QA pair now runs LocalDb replication,
connected); tier note gains the deployed-state line and the winrm access path.

deployment.md: §2.1 access rows replaced by the winrm skill (WinRM 5985 +
SMB 445; servecli/psbridge retired), §7.1 port map gains 5985/445 and marks
6150 retired, live-state table updated (OtOpcUa active flipped to node-a),
new "Deployed builds on QA" paragraph, §9 deployed-state summary.

Claude-Session: https://claude.ai/code/session_01RgthVLVU5CJ8SUuEwruTkt
2026-09-10 12:37:44 -04:00
Joseph Doherty 3903c9a196 index: ScadaBridge main @ fef3e767 — 2026-09-09 arch-review remediation merged (13 High + 33 Medium) 2026-09-09 22:10:21 -04:00
Joseph Doherty ef487957b2 docs: ScadaBridge index — flow debugger script entry
Claude-Session: https://claude.ai/code/session_01NcMG6xXdsJbmD2wYAgkK29
2026-09-08 01:21:47 -04:00
Joseph Doherty 895e881807 docs(index): ScadaBridge row — Flow Debugger shipped and arch-review remediated (main @ 789377ef)
Claude-Session: https://claude.ai/code/session_01NcMG6xXdsJbmD2wYAgkK29
2026-09-06 17:11:19 -04:00
Joseph Doherty 54f111e8b1 docs(btdb): register BTDB Manager in the Overview docker registry; record the local rig
- ZB.MOM.WW.Overview appsettings.Docker.json: application "BTDB Manager", instance manager at
  http://zb-btdb-manager:9877 (HasActiveRole false); docker/README.md fleet row.
- CLAUDE.md BTDB row and sister-project-history/btdb.md §7/§9: docker/ layout, the
  dacpac + SQL CLR side-project build, scadabridge-mssql as the BT host.

Claude-Session: https://claude.ai/code/session_015dYqtaTxgf6NK2KuwriMSg
2026-09-04 06:14:22 -04:00
Joseph Doherty 370a9eea96 docs(btdb): record the BTDB Manager Blazor conversion (feat/manager-blazor) in the index and history
Claude-Session: https://claude.ai/code/session_015dYqtaTxgf6NK2KuwriMSg
2026-09-04 05:46:05 -04:00
Joseph Doherty 4988c24618 docs(btdb): Manager batch-edit path now carries ContainerID/MoveOutTimestamp (btdb feat/machine-batch-transfer)
Claude-Session: https://claude.ai/code/session_01Wzg6NUCWHipSexLs2cgRFv
2026-09-03 14:39:14 -04:00
Joseph Doherty fe6216c533 docs(index): BTDB is now a git checkout; DARS BatchTracker_DB fork migrated onto btdb feat/machine-batch-transfer (local, unpushed)
Claude-Session: https://claude.ai/code/session_01Wzg6NUCWHipSexLs2cgRFv
2026-09-03 14:34:20 -04:00
Joseph Doherty 10990a43c8 docs(index): add BTDB (Batch Tracking Database) as a sister project + analysis
Row in the sister-project table, a BTDB-edges subsection (Galaxy write contract, ScadaBridge inbound-API SAPID lookup on db-connection BTDB, Historian CLR/INSQL co-location), break-surface note, Windows-only build commands, and the DARS bullet now points at the unversioned WW_ARCH/BatchTracker_DB fork. Full schema/contract notes and the 2026-09-03 gap analysis live in .claude/skills/sister-project-history/btdb.md.

Claude-Session: https://claude.ai/code/session_01Wzg6NUCWHipSexLs2cgRFv
2026-09-03 14:15:34 -04:00
Joseph Doherty e538ea36e3 docs(index): track .claude/skills/sister-project-history — the OtOpcUa/HistorianGateway narratives split out in c72271a were gitignored and existed only locally
.gitignore ignored all of .claude/, so the per-project history files the root index points at were never committed; the pushed index had lost that history. Un-ignore .claude/skills/ (settings.local.json and worktrees stay ignored) and add the three files.

Claude-Session: https://claude.ai/code/session_01Wzg6NUCWHipSexLs2cgRFv
2026-09-03 14:15:34 -04:00
Joseph Doherty 63e6d3f867 docs(index): all four apps on Auth 0.3.0, OtOpcUa on LocalDb 0.3.4, MxGateway.Client/Contracts 0.2.1; Secrets consumer matrix corrected to 0.6.2 everywhere
Family-wide pin refresh of 2026-09-03: OtOpcUa b8b4c18f, mxgw 4f931e4,
HistorianGateway d8d890c, ScadaBridge e45c4af9 (Auth already on main).
Per-library narratives in ZB.MOM.WW.Auth/CLAUDE.md and
ZB.MOM.WW.LocalDb/CLAUDE.md updated to match; the stale
"unpushed / 0.6.0 / 0.5.1 / merge pending" notes are corrected.

Claude-Session: https://claude.ai/code/session_01Wzg6NUCWHipSexLs2cgRFv
2026-09-03 11:25:29 -04:00
Joseph Doherty c72271aa8a docs: split per-library history out of the root index into ZB.MOM.WW.*/CLAUDE.md files
Claude-Session: https://claude.ai/code/session_01Wzg6NUCWHipSexLs2cgRFv
2026-09-03 10:48:29 -04:00
Joseph Doherty 2e545b50da docs+tools: UG_WW_* AD group -> app role mapping proposal (ldap_mapping.md); tools/sql/Ensure-SysadminLogin (create/repair a SQL login with a parameter-bound password, optional sysadmin grant)
Claude-Session: https://claude.ai/code/session_013L3XdmVii9i5sY4FChU8pB
2026-09-02 23:55:53 -04:00
Joseph Doherty 6acc5c1908 docs(index): ScadaBridge entry — inbound API keys on the shared SQL Server store on central pairs; pins Auth 0.3.0
Claude-Session: https://claude.ai/code/session_013L3XdmVii9i5sY4FChU8pB
2026-09-02 23:31:21 -04:00
Joseph Doherty c54cd808f4 docs(index): Auth 0.3.0 on the feed — ApiKeys.SqlServer package, consumer matrix, version narrative; apps still pin 0.2.1 pending ScadaBridge adoption
Claude-Session: https://claude.ai/code/session_013L3XdmVii9i5sY4FChU8pB
2026-09-02 22:43:07 -04:00
Joseph Doherty de21669ad5 feat(auth)!: 0.3.0 — ZB.MOM.WW.Auth.ApiKeys.SqlServer package (AddZbApiKeyAuthSqlServer, importer), README/changelog
The `!` marks the new package + version, not an API break — SQLite stays default and
existing consumers need no code change.

Claude-Session: https://claude.ai/code/session_013L3XdmVii9i5sY4FChU8pB
2026-09-02 14:39:35 -04:00
Joseph Doherty dcee4199ab feat(auth.apikeys.sqlserver): SqliteApiKeyStoreImporter — idempotent insert-where-not-exists copy of keys + audit (union across a pair)
Claude-Session: https://claude.ai/code/session_013L3XdmVii9i5sY4FChU8pB
2026-09-02 14:35:31 -04:00
Joseph Doherty b5da1c8c57 feat(auth.apikeys.sqlserver): IApiKeyStore/IApiKeyAdminStore/IApiKeyAuditStore over SQL Server, semantics pinned by the SQLite contract tests re-run live
Claude-Session: https://claude.ai/code/session_013L3XdmVii9i5sY4FChU8pB
2026-09-02 14:29:58 -04:00
Joseph Doherty c1e34c307e feat(auth.apikeys.sqlserver): zbauth schema v1 + concurrent-boot-safe migrator (retry on 1205/2714/1913/2627, newer-version fail-closed); live tests gated on AUTH_SQLSERVER_CONNSTR
Claude-Session: https://claude.ai/code/session_013L3XdmVii9i5sY4FChU8pB
2026-09-02 14:22:25 -04:00
Joseph Doherty 2969805e4e feat(auth.apikeys.sqlserver): package skeleton, options (schema default zbauth, validated) and connection factory
Claude-Session: https://claude.ai/code/session_013L3XdmVii9i5sY4FChU8pB
2026-09-02 14:08:22 -04:00
Joseph Doherty 3f11704d10 feat(auth.apikeys): IApiKeyStoreMigrator abstraction — SQLite implements it, DI registers it via TryAdd so a provider registered first wins; ApiKeyAdminCommands accepts the interface (old ctor kept)
Claude-Session: https://claude.ai/code/session_013L3XdmVii9i5sY4FChU8pB
2026-09-02 14:06:14 -04:00
Joseph Doherty 300094e792 docs(index): LocalDb 0.3.4 published — snapshot as_of_seq floors at last_acked_seq (ScadaBridge register row 106); ScadaBridge pins 0.3.4 2026-08-20 10:00:39 -04:00
Joseph Doherty 75c1897522 fix(localdb): snapshot as_of_seq floors at last_acked_seq so a rebuilt peer's watermark is lifted — ends the full-snapshot-on-every-reconnect loop (0.3.4, ScadaBridge register row 106)
SnapshotStreamer.SendAsync stamped as_of_seq = MAX(seq), which reads 0 once ack-pruning has
emptied a converged sender's oplog. A receiver whose watermark genuinely is 0 (a rebuilt node —
ScadaBridge's site-a-a since its 2026-08-15 rebuild) was healed by the snapshot but never lifted
by it (the receiver's watermark update is correctly MAX-guarded), so the 0.1.2 empty-oplog
horizon rule saw 0 < last_acked_seq as a gap on every subsequent handshake and re-streamed the
whole database on every reconnect until the sender wrote again. Observed live: the same 127k-row
full snapshot on two consecutive restarts of the pair.

Fix: as_of_seq = max(MAX(seq), last_acked_seq). Every delta pruned below last_acked_seq is
already folded into the rows the snapshot carries, so that is the floor it may claim; the
receiver's MAX guard then lifts the watermark and the next handshake finds no gap. Sender-side
only; wire-compatible; no schema change.

Test WipedPeer_SnapshotLiftsItsWatermark_SoTheNextReconnectSendsNoSecondSnapshot fails on the
unfixed code exactly as the rig does (watermark 0, expected 3) and passes with the fix: the
second episode exchanges only a delta, and a capturing logger on the snapshot streamer proves
no snapshot was sent. Suite 216/216 on 8 of 9 runs; one unnamed single-test failure on the first
run did not recur in eight further runs and could not be attributed.
2026-08-20 09:52:19 -04:00
Joseph Doherty 5e02c1c38f docs(index): LocalDb 0.3.3 published — FK-parent registration guard + atomic per-entry apply (ScadaBridge arch-review P4-7); ScadaBridge pins 0.3.3 2026-08-20 08:50:26 -04:00
Joseph Doherty 9663279594 fix(localdb): preserve the poison cause when dead-lettering itself fails; pin self-referencing cascade (0.3.3 review follow-ups)
Three review follow-ups on 122940c. Still 0.3.3 — unpublished, so no further
version bump. No behaviour change to any succeeding path.

- The per-entry poison handler's recovery work (ROLLBACK TO + the dead-letter
  INSERT) was unguarded: a wedged connection, an I/O error, or a dead-letter
  INSERT that faults would propagate the SECOND exception and silently discard
  the FIRST — the one that says why the entry was poison at all. The pair is now
  wrapped; a recovery failure throws an AggregateException whose message names
  the entry (table + seq) and the recovery fault, and whose InnerException is the
  ORIGINAL entry fault, with the recovery fault carried alongside it at
  InnerExceptions[1] with its own stack. The outcome is unchanged and still
  fail-closed: nothing commits, and disposing the batch transaction unwinds it.
  OperationCanceledException is deliberately excluded from the wrap so a
  shutdown still surfaces as a cancellation rather than as a fault. No upstream
  caller catches SqliteException from the apply path (checked), so widening the
  escaping type is safe.

  Injected cheaply after all: a RAISE(ABORT) trigger on __localdb_dead_letter,
  stacked on the existing row-version poison trigger, produces exactly the
  two-fault case with no production test seam. The test asserts both causes are
  carried AND that the batch committed nothing — the entry that applied cleanly
  before the poison one is gone and the peer watermark never moved.

- Register_SelfReferencingCascade_Throws pins the README's "or from itself"
  claim: a table that is its own cascading parent (parent_id REFERENCES
  nodes(id) ON DELETE CASCADE) is refused. The guard needed no special case —
  it reads every foreign key in the database — but the promise is now tested.

- Comment on why EnterEntryAsync sits outside the try: a SAVEPOINT that failed
  opened nothing, so a handler ROLLBACK TO would name a savepoint that does not
  exist and fault in turn.

Both new tests were run against 122940c first and fail there: the self-reference
case throws nothing, and the stacked-fault case escapes as a bare
SqliteException("dead-letter write failed") with the original cause gone.

Suite: 215/215 green, build 0 warnings / 0 errors.
2026-08-20 08:49:11 -04:00
Joseph Doherty 122940c0e4 fix(localdb): refuse cascading-FK parents at registration; make an entry's row+ledger writes atomic (0.3.3, ScadaBridge arch-review P4-7)
Two latent apply-path hazards from the ScadaBridge adversarial architecture
review. Neither has a live trigger in any current consumer — ScadaBridge's ten
replicated tables carry no foreign keys at all (verified against the running rig's
site-localdb.db) and OtOpcUa's LocalDb tables carry none either — but both are the
kind that surface as silent divergence rather than as an error, so they are closed
before a consumer's schema grows into them.

Wire-compatible: no proto change, no lib_schema_version bump, no on-disk schema
change. No consumer code change.

- RegisterReplicated now refuses a table that is the PARENT of a foreign key with
  a row-mutating ON DELETE action (CASCADE / SET NULL / SET DEFAULT), naming the
  offending child column and action. The apply path writes remote rows with
  INSERT OR REPLACE, whose PK-conflict resolution DELETES the existing row first;
  connections run PRAGMA foreign_keys=ON, so that implicit delete fires the child's
  ON DELETE action while the capture guard is raised. The child rows would change
  on the applying node only, produce no oplog entry, and diverge the pair with
  nothing able to detect it — LWW compares only rows it was told about. RESTRICT /
  NO ACTION stay allowed: they abort the statement instead of mutating rows behind
  capture's back, which the apply path already handles as per-entry poison. The
  check inspects every foreign key in the database and runs at registration;
  SQLite cannot add a foreign key to an existing table, so a child table created
  later is caught at the next startup's registration, not at the DDL. Documented
  on ILocalDb.RegisterReplicated and in the README's limitations list.

- An entry's row write and its ledger write are now atomic with each other. They
  are two statements and SQLite aborts only the failing one, so a statement-level
  fault between them — the case the per-entry poison catch exists for — committed
  a half-applied entry: a tombstone whose table row was gone while
  __localdb_row_version still called it live (SnapshotStreamer can only warn and
  skip that, so the peer never learns the row died), or an upsert whose new row
  carried the OLD version and therefore lost the next comparison it should have
  won. The pair now runs inside a per-entry SAVEPOINT, rolled back (and released,
  so nothing nests) before dead-lettering, leaving both writes or neither while
  the rest of the batch proceeds and commits.

Every new test was run against the unfixed code first and fails there with exactly
the divergence shape described: the tombstone case reads back null instead of the
live row, the upsert case reads back the remote row against an unchanged ledger,
and the registration cases throw nothing.

Suite: 213/213 green, build 0 warnings / 0 errors.
2026-08-20 08:40:14 -04:00
Joseph Doherty e9dc13689a docs(index): LocalDb 0.3.2 published — cap-prune session fault, sync keepalives, newest-wins stream guard (ScadaBridge arch-review P4-1 + P4-3); ScadaBridge pins 0.3.2 2026-08-19 15:06:47 -04:00
Joseph Doherty f62b017cc7 fix(localdb): fault live sync session on cap-prune; keepalive + newest-wins sync guard (0.3.2, ScadaBridge arch-review P4-1 + P4-3) 2026-08-19 15:02:04 -04:00
Joseph Doherty dbcbc5bd41 docs(index): LocalDb 0.3.1 published — handshake-fault control-lane flush (register row 41) 2026-08-18 07:30:59 -04:00
Joseph Doherty 1145df682e docs(index): OtOpcUa now registers LocalDb tables conditionally — baseline on enable, deregister self-heal on disable (row 39 closed) 2026-08-18 07:25:18 -04:00
Joseph Doherty 3e5a5fde81 fix(localdb): flush the control lane before a faulting session cancels its writer (0.3.1)
A session that faulted during the handshake cancelled its writer loop immediately,
which could kill its OWN Handshake while it still sat in the control lane: the
enqueue -> receive -> validate -> fault path has no yields, while the writer's
wakeup waits in the thread-pool queue, so with the peer's handshake already
buffered the cancel won the race almost every time (39/40 in the new pinning
test). Mismatch detection is symmetric — the peer computes its fail-closed
verdict FROM our Handshake — so the healthy peer never learned anything: in
tests it waited out the full 15 s receive cap (the register-row-41 flake on
SyncSessionTests.Handshake_DigestMismatch_FailsClosed), and in production it
would misclassify a permanent schema mismatch as a generic disconnect and
reconnect-loop at the fast backoff instead of taking the classified
FailedPrecondition -> LogError + max-backoff path.

RunAsync's fault teardown now completes both lanes so the writer drains what is
already enqueued and exits on its own, with a 2 s deferred cancel as the backstop
for a wedged transport. Caller-initiated cancellation is unchanged (the linked
token is already cancelled, so shutdown is not delayed), and nothing on the wire
changes — a 0.3.0 peer simply receives the Handshake it was always owed.

New SyncSessionTests.Handshake_FaultTeardown_StillTransmitsTheLocalHandshake pins
the race (40 concurrent preloaded-mismatch sessions; 39/40 red pre-fix, green
post-fix).

BatchBudgetTests hardened separately: the register's other flaky test
(Pump_RowLargerThanTheBudget_IsSentAloneRatherThanStallingTheStream) awaits the
scripted-peer channel without ever observing the session task, so ANY session
fault surfaced as an opaque 15 s timeout. A run-observing NextAsync overload now
races the session task at every read site in the class, so the next flake reports
the session's real exception instead. (The handshake-race root cause does not
structurally apply to this test — no handshake fault occurs there — so its
intermittent timeout is attributed to the fault-hiding wait, now removed.)

Suite 200/200 green. Closes ScadaBridge deferred-work register row 41 (cross-repo).
2026-08-18 07:11:14 -04:00
Joseph Doherty b62981ff80 fix(build): anchor pack/push scripts to their own repo root (0038d46 pattern, all seven)
Secrets/push.sh, Theme/pack.sh+push.sh, Audit/pack.sh+push.sh and Auth/pack.sh+push.sh
all carried the CWD-pack bug LocalDb's push.sh was cured of in 0038d46: a bare
'dotnet pack -c Release -o ./artifacts' packs whatever solution sits in the CALLER's
working directory, and the push scripts then shove the caller's ./artifacts/*.nupkg
onto the live Gitea feed (the incident that briefly published 25 unrelated packages).

Each script now cds to its own repo root, names its .slnx explicitly, writes to an
absolute artifacts path, and (push.sh) pushes an anchored glob. Verified by bash -n on
all seven plus a positive control: Audit's pack.sh run from a foreign CWD packed only
ZB.MOM.WW.Audit into its own artifacts dir and left the caller's directory untouched.
Push scripts deliberately NOT executed (they publish); pack half verified only.

Closes ScadaBridge deferred-work register row 42 (cross-repo).
2026-08-18 07:00:42 -04:00
Joseph Doherty 31a7c8a88a docs(index): LocalDb consumer pins — OtOpcUa 0.1.3 -> 0.2.1 (R4 merged), skew note updated for 0.3.0 2026-08-15 04:15:28 -04:00
Joseph Doherty 7757b9c6fc Merge branch 'localdb-per-table-snapshot' — LocalDb 0.3.0: per-table needs_snapshot, capability-negotiated partial snapshots (ScadaBridge R1) 2026-08-15 04:15:02 -04:00
Joseph Doherty 0038d46c9a fix(build): push.sh must pack ITSELF, not the caller's working directory
dotnet pack with no project argument packs whatever solution sits in the caller's
CWD, so invoking this script by absolute path from another repo's checkout packed
and published 25 unrelated packages to the live Gitea feed under its name. Now it
cds to its own repo root and names the solution and an absolute output path.
2026-08-15 03:36:48 -04:00
Joseph Doherty cea3930b94 feat(localdb): per-table needs_snapshot (0.3.0, on-disk schema v3)
Baselining one table used to set a single per-DATABASE needs_snapshot bit, and a
snapshot streams every registered table in full — so opting one table into
replication late re-sent all of them, in both directions at once on a pair
enabling replication late. On a database holding a high-volume table (an event
log at its retention cap) that is the largest transfer this library performs.
0.2.1 documented the cost and deferred the fix as needing an on-disk change.

Schema v3 adds __localdb_snapshot_state (table_name PK, needs_snapshot), created
by the shared DDL with IF NOT EXISTS so an older file gains it on open; the v2->v3
transition is a version stamp only. RegisterReplicated(..., baselineExistingRows:
true) now flags that table alone. The database-wide flag survives unchanged for
the paths that genuinely reach every table — a cap prune or an impossible peer ack
loses delta continuity for the oplog as a whole. DeregisterReplicated drops a
table's pending flag with its ledger rows, since nothing would ever stream (and so
clear) it afterwards.

Wire compatibility is additive and negotiated by CAPABILITY, not version:
lib_schema_version stays 1 because ValidateHandshake compares it fail-closed for
equality, so bumping it would stop 0.1.x/0.2.x pairs syncing outright. Handshake
gains supports_partial_snapshot (field 5) and SnapshotBegin gains a tables scope
(field 2) where EMPTY means all tables — precisely what a pre-0.3.0 sender emits
and what a pre-0.3.0 receiver assumes. A peer that does not advertise the
capability is served a full snapshot: a scoped one would make it advance
last_applied_remote_seq to the snapshot's as-of and silently discard every delta
below it for the tables left out.

For the same reason a partial snapshot moves no watermark on either side. The
receiver keeps last_applied_remote_seq (carrying only the HLC across, which is
MAX-guarded), and the sender keeps _sentThruSeq, so the deltas the snapshot
overlaps are still pumped and merged by LWW.

Crash safety: snapshot debt now clears on the receiver's new SnapshotAck rather
than on enqueue, so an ungraceful exit part-way through re-streams the same scope
on reconnect. The ack rides the unbounded CONTROL lane like DeltaAck, so it
composes with 0.2.1's bounded 64-message inbox and its out-of-handshake snapshot.
Against a pre-0.3.0 peer the 0.2.x clear-on-enqueue behaviour is kept — there is
no ack to wait for — with the handshake's horizon gap check as the net.

Tests 199/199 (was 188): single-table baseline streams only that table, mixed-
version interop (peer without the capability gets a full snapshot), debt standing
until SnapshotAck, partial snapshot not advancing the receiver's watermark, no
SnapshotAck emitted to an old peer, end-to-end over two real databases, plus v2->v3
upgrade and per-table flag isolation.

README, ILocalDb remarks (which named this as the follow-up) and the umbrella
CLAUDE.md index updated.
2026-08-15 03:34:54 -04:00
Joseph Doherty f627cee9c0 Merge branch 'localdb-perf-remediation' 2026-08-15 01:46:38 -04:00
Joseph Doherty 14cb283172 docs(index): LocalDb 0.2.1 — HLC anchor on deregister + bounded sync inbox
The umbrella LocalDb row and the pack/test quick-reference now name 0.2.1 (188 tests,
3 nupkgs on the feed). Records both findings, the snapshot-out-of-handshake change that
bounding the inbox required, and the deferred per-table needs_snapshot. Consumer pins are
unchanged: ScadaBridge still pins 0.2.0, OtOpcUa still pins 0.1.3.
2026-08-14 23:35:57 -04:00
Joseph Doherty 522cfbfda6 fix(localdb): flush the HLC anchor on deregister, bound the sync inbox (0.2.1)
Two adversarial-review findings against 0.2.0. Wire-compatible with 0.1.x/0.2.0 peers:
no proto change, no lib_schema_version bump, no on-disk schema change.

F4 — DeregisterReplicated destroyed the HLC clock's only durable crash anchor. Clock
recovery on open is MAX(hlc_high_water, MAX(oplog.hlc), MAX(row_version.hlc),
last_seen_hlc); hlc_high_water is written only by Dispose, and deregistration deletes the
table's rows from BOTH ledgers. On a file whose registered tables have all been
deregistered, an ungraceful exit (crash, SIGKILL, power loss) therefore left nothing above
zero to recover from: the reopened clock restarts from wall-clock time and can re-issue
stamps below HLCs peers already hold, which LWW discards as older. The current clock is now
flushed inside the deregistration transaction, before the prune, as a separate command so
it cannot inflate the "did anything change?" answer. FlushHlcHighWater takes an optional
transaction (SQLite rejects a command with no transaction on a connection that has one) and
is now MAX-guarded — every writer of that column is flushing a monotonic clock, so a lower
value can only be stale.

F3 — the sync inbox was Channel.CreateUnbounded, making inbound memory a function of what
the PEER sends. The bad case is not hypothetical: a snapshot streams every row of every
registered table, needs_snapshot is per-database, and both sides of a pair that enables
replication late baseline unconditionally — so a mutual full snapshot of a large dataset
(an event log near its storage cap) was buffered whole, in memory, on both nodes at once.
The inbox is now bounded at 64 messages with wait-mode backpressure, so the ceiling is
~64 x MaxBatchBytes — a configured number rather than a peer-controlled one — and a full
inbox stops draining the gRPC stream, which closes the peer's flow-control window. The
pump writes with WriteAsync, not TryWrite: on a full bounded channel TryWrite drops the
message, and every inbound message is protocol state.

Bounding alone would have deadlocked the very case it was aimed at. The snapshot a node
owes was streamed from INSIDE the handshake, before the receive loop existed, so neither
side drained its inbox while sending; a mutual snapshot converged only because the inbox
was unbounded. The snapshot now runs as the first phase of the outbound task, started
alongside the receive loop, so the inbox is drained for the whole life of the session.
Interleaving needed no new safety: snapshot rows and deltas both merge through LWW and the
snapshot's watermark write is MAX-guarded. Ordering within the outbound lane is preserved
(the pump still starts only after the snapshot, from its as-of seq).

Per-table needs_snapshot (the finding's optional third part) is NOT done: the flag lives in
__localdb_peer_state and narrowing it needs an on-disk schema change, which this fix
deliberately avoids. Documented as a follow-up, and the cost is now written down where it
is decided — RegisterReplicated(baselineExistingRows) remarks and the README both say that
baselining one table re-streams every registered table in both directions, and that
high-volume tables should be trimmed before enabling replication late.

188/188 tests pass (was 184). New coverage: the deregistered clock anchor surviving an
ungraceful reopen (a second instance over the same file with no Dispose — fails without the
flush, recovering at 0), the flush not counting as work done, bounded-inbox backpressure
under a slow reader (the pump stalls at the bound and loses nothing, proven by contiguous
in-order delivery), and a mutual snapshot over a capacity-1 transport converging — that
last one deadlocks and times out against the old handshake-phase snapshot ordering.

Version 0.2.1.
2026-08-14 23:34:55 -04:00
Joseph Doherty 1ce0c5955f docs: umbrella index — LocalDb 0.2.0 + ScadaBridge consumption 2026-08-14 22:21:41 -04:00
Joseph Doherty 9377fa1678 perf(localdb): dereg API, O(1) backlog depth, byte-budget batching, prepare-once apply (0.2.0)
WP3.3 of the ScadaBridge architectural-review remediation. Six changes, all
wire-compatible with 0.1.x peers — no proto change, no lib_schema_version bump. The
on-disk bookkeeping schema goes to v2 and is upgraded in place when a file is opened.

DeregisterReplicated(table). There was no way to stop capturing once a file had been
registered, so a node that does not replicate kept paying three triggers inside every
write transaction, appending to an oplog nothing would ever drain. Drops the triggers and
prunes the table's oplog + row-version rows in one transaction; idempotent, and
deliberately usable on a table this process never registered, since stale triggers left by
an EARLIER build are the primary case. Deregistration must be symmetric across a pair, and
already is enforced: the handshake compares registered-table digests fail-closed, so a node
that drops a table its peer still replicates stops syncing loudly rather than diverging.

RegisterReplicated(table, baselineExistingRows: true). Closes the late-opt-in hole: the
snapshot streamer pages from __localdb_row_version, which only triggers populate, so a node
that started replicating LATE never sent its pre-existing rows — silently, forever. Seeding
alone would not have fixed it, because a node whose oplog starts at seq 1 presents no gap at
the handshake and is told it needs no snapshot; the seed therefore also flags needs_snapshot,
and the existing resync machinery carries the rows. The floor is HLC 0 stamped with this
node's id: every genuine HLC is a UTC millisecond shifted left 16 bits and so is strictly
greater, which makes a baselined row lose every comparison against a real remote write and
win only where the peer has no version of that key at all. Two nodes baselining the same key
both hold 0 and resolve by the node-id tie-break — convergent, and nothing better is
available for two rows of unordered antiquity. Opt-in, so the documented CDC contract is
unchanged unless asked. Pruning the ledger on deregister is safe precisely because
re-registration can re-baseline; the two APIs are a pair.

O(1) backlog depth. GetOplogDepth ran COUNT(*) over the entire unacked backlog, once a
minute from maintenance AND on every metrics scrape — a full scan of a million rows exactly
when a node is already behind. Now MAX(seq) - MAX(last_acked_seq, MIN(seq) - 1), floored at
0: three b-tree seeks, measured at 58 VM steps against 100,020 for the count on a 50k
backlog. Exact, because seq is AUTOINCREMENT and every prune path removes a prefix (ack
pruning by watermark, the row cap by count, the age cap by an HLC cutoff that rises with
seq). The MIN clamp is what keeps it exact after a cap prune has moved the horizon above a
stalled watermark — without it the caps would re-flag on every tick forever.

Byte-budget batching. MaxBatchSize was the only cap on an outbound message, which made it a
proxy for a byte budget that consumers had to tune against their widest row: ScadaBridge
pinned it to 16 because 70 KB config_json times the 500 default is ~35 MB against a 4 MB
gRPC limit. MaxBatchBytes (default 2 MB) now bounds delta and snapshot messages by summed
serialized size, with the row count demoted to a secondary cap. A row larger than the budget
is sent alone rather than stalling the stream on it. Since more, smaller messages would
otherwise mean more apply transactions and more acks, inbound delta batches and acks ALREADY
queued are coalesced — one transaction and one ack per burst, bounded by the sender's own
caps, and a no-op under a trickle.

LwwApplier prepares each statement once. It went through the generic transaction façade,
which builds a fresh SqliteCommand per call: three SQL parses per applied row, on the path
that drains a reconnect backlog. Statements are now held for the batch and rebound.

Dropped __localdb_oplog_hlc. It indexed (table_name, pk_json, hlc), which no query has ever
used — every oplog access path is by seq or a full hlc-predicate delete — while costing a
b-tree insert inside every captured consumer write.

184/184 tests pass (was 149). New coverage: schema upgrade drops the index and preserves
identity/watermarks/data, deregistration idempotency and trigger absence and cross-process
cleanup, baseline seeding at the floor with LWW safety proved through the real applier,
depth asserted equal to the counting query across every prune scenario plus a constant-time
assertion over a 200k backlog, byte-budget chunking including the one-giant-row edge on both
the delta and snapshot paths, prepare-once statement counting, and coalescing that must not
swallow the message that ends its run.

Version 0.2.0.
2026-08-14 22:08:43 -04:00
Joseph Doherty 92246c9734 docs(inventory): full QA §7.1 refresh for the 2026-08-14 VQ04 singleton clone — 10-instance fleet, psbridge :6150 + glauth :3893 port rows, VQ04→VQ03 Galaxy/alarm dependency; CLAUDE.md Overview note updated 2026-08-14 12:39:14 -04:00
Joseph Doherty 1fee9755d7 docs(deployment): VQ04 now runs its own MxGateway/HistorianGateway/Overview (cloned from VQ03 2026-08-14, shared API-key stores); QA access = psbridge :6150, servecli retired 2026-08-14 12:35:56 -04:00
Joseph Doherty 205bddb3b8 docs(plan): flag ignitionoee LDAP as ON HOLD -- needs new UG_WW_* groups minted first 2026-08-13 15:01:15 -04:00
Joseph Doherty 206c588608 docs(plans): VD03 NAM AD LDAP cutover plan (not executed) 2026-08-13 09:24:17 -04:00
Joseph Doherty bd929d98fc docs(ldap): e2e NAM AD login verified via HG docker -- svc_igntadmin, stage diagnostics 2026-08-13 09:17:42 -04:00
Joseph Doherty 990f4c018d docs: HG e42ff31 is on main, not a branch 2026-08-13 08:58:21 -04:00
Joseph Doherty 5da4ab3ebd docs(index): HistorianGateway UI-sweep branch merged to main (e42ff31) — Theme 0.4.1 + Health 0.3.0 + Secrets 0.6.2 + Auth 0.2.1 now on its default 2026-08-13 08:58:09 -04:00
Joseph Doherty 3d2f3f59b2 docs(index): Auth 0.2.1 adoption commits pushed on all four apps 2026-08-13 08:52:25 -04:00
Joseph Doherty 58c2e14c38 docs(index): Auth 0.2.1 adopted by all four apps; FallbackServers live-gated on HG + ScadaBridge rig 2026-08-13 08:49:25 -04:00
Joseph Doherty 58f605609d feat(infra): redundant GLAuth pair for FallbackServers failover drills
Two local glauth containers (zb-ldap-primary :3893 / zb-ldap-backup :3894)
simulating the NAM two-DC topology, so the primary can be killed during a
drill without touching the shared 10.100.0.35 instance. Drill recipe +
verified-PASS record (HistorianGateway, 2026-08-13) in the README.
2026-08-13 08:28:05 -04:00
Joseph Doherty f42aa14033 docs(inventory): add the QA stack (vq03/vq04/sql-vq03) and correct vd03 DEV-vs-prod
deployment.md:
- §1/§2.1: add wonder-app-vq03, wonder-app-vq04 and wonder-sql-vq03 with IPs and
  per-host roles; new §7.1 QA port map + live active/standby state.
- QA is a real 2-node HA pair (ScadaBridge central+site pairs, OtOpcUa pair) where
  DEV is a single all-in-one box, so it is the only environment here that exercises
  failover and leader election. MxGateway/HistorianGateway/Overview run on vq03 only.
- Every QA fact is marked scan (port probe) or dash (read off the QA Overview
  dashboard's live polling). No QA config file was read; connection strings and
  service names stay unverified.
- Correct the tier: vd03 is DEV, not production (vd=dev, vq=qa, per
  mes-delmia-integration-api.md §1.1). Its ASPNETCORE_ENVIRONMENT really is
  "Production" -- a .NET overlay name, orthogonal to the tier, and the likely source
  of the original error. No production box has been identified.
- Record that QA requires Basic auth on /management where DEV does not, so DEV-only
  procedures relying on unauthenticated management calls will not work on QA.
- Record that inbound API keys never cross environments (per-stack peppered-HMAC,
  excluded from config bundles) plus the 401-vs-400 probe, with the caveat that auth
  runs before route resolution so a 401 needs a positive control.
- Withdraw the SSH-on-2222 claim made earlier in this same pass: all three wonder
  boxes accept TCP on 2222 and send no SSH banner, so servecli is not serving SSH and
  no shell access was available. Port scan cannot establish a service; banner grab can.

CLAUDE.md:
- Overview: record the second instance on wonder-app-vq03:5320, and that its real-FQDN
  registry is correct rather than a divergence -- the 127.0.0.1 rule is specific to
  vd03 co-locating every instance on one host.
- Add the DEV-vs-prod note pointing at deployment.md §2.1/§7.1.
2026-08-13 08:08:23 -04:00
Joseph Doherty 818775b311 docs(index): Auth 0.2.1 published -- AD referral fix + NAM group findings
CLAUDE.md: feed now carries 0.2.1; record the referral defect and that every
app is still exposed until it bumps off 0.1.5 (a functional fix, not
housekeeping), plus the new tools/LdapProbe.

ldap_setup.md: findings from probing the live NAM directory --

- LDAPS 636, StartTLS 389 and plain 389 all connect on both DCs. The only TLS
  chain error is UntrustedRoot, so installing zimmer-rootca is sufficient; the
  RSA 1024-bit key is rejected only by OpenSSL at SECLEVEL=2, i.e. Debian .NET
  containers, not by macOS or Windows hosts.
- The UG_WW_* Wonderware group convention, 39 groups enumerated directory-wide.
  This partly overturns this doc's earlier "no group->role convention exists"
  claim: that was true of Ignition, which was the only source audited, and
  false of the domain. Three shapes with a consistent role suffix (ADMIN, RO,
  OPERATOR, ENGINEER, SUPERVISOR, TESTER) across environment and site axes.
- A proposed mapping onto CANONICAL-ROLES, with the three gaps left open
  rather than guessed: SUPERVISOR/TESTER have no canonical equivalent, nothing
  maps to Deployer, and the DEV/QA/PROD axis is orthogonal to role so it must
  ride in the per-project scope payload or the role set triples.
- The referral defect and its fix.
2026-08-12 21:27:23 -04:00
Joseph Doherty 4e01cbc2c3 feat(tools): ldapprobe -- NAM AD auth + group discovery probe
Diagnostic for pinning down the LDAP settings the four ZB.MOM.WW apps need
against the Zimmer NAM domain, and for answering which AD groups can be mapped
to app roles. Found the referral defect fixed in 0.2.1.

Two independent halves in one run:

Part A drives the REAL ZB.MOM.WW.Auth.LdapAuthService -- same bind-then-search-
then-bind, same options validator, same failure enum -- so its verdict IS what
the apps produce rather than an approximation of it.

Part B asks the directory what the library cannot, which is where the group
answer comes from: full group DNs, nested groups via
LDAP_MATCHING_RULE_IN_CHAIN, the primary group (AD omits it from memberOf, so
it can never be a role group), security vs distribution type, decoded
userAccountControl, referral counts, and the TLS chain with key sizes.
--list-groups '<pat>' enumerates every matching group in the directory, which
a membership dump structurally cannot do -- it only ever shows one account's
memberships.

Passwords are prompted for and never echoed; they cannot be passed as
arguments, which would put them in shell history. --self-bind lets the user
under test stand in for the service account, so group discovery does not
require the svc_igntnapp secret.

Not packable, outside the Auth solution and its central package management,
referencing the Auth projects directly so it tracks current source.
2026-08-12 21:27:14 -04:00
Joseph Doherty 1f8ab8e3b3 fix(auth): skip AD continuation referrals in LDAP search (0.2.1)
Active Directory answers any search based at a domain root with continuation
references (CN=Configuration, DC=ForestDnsZones, ...). With referral following
disabled -- the default, and what we want, since chasing one would re-bind
somewhere we never authenticated -- Novell surfaces each by throwing
LdapReferralException from Next().

That escaped NovellLdapConnection.Search, and LdapAuthService maps a failed
search to ServiceAccountBindFailed. So every login against
SearchBase = DC=nam,DC=zimmer,DC=com failed system-side on BOTH DCs in ~546 ms
while the directory, the credentials and the service account were all healthy.
Identical on each endpoint, so failover could not help either.

A continuation reference is a pointer to another naming context, never a
statement that this search failed, so the loop now skips them and continues --
returning exactly the entries in the naming context we bound to. Extracted as
ReadEntries(ILdapSearchResults) so the handling is unit-testable through the
Novell seam without a live directory. A 1000-referral cap guards a client that
throws without advancing, which would otherwise spin forever inside a
fail-closed auth path.

Non-referral faults still propagate untouched: swallowing those would turn
"the directory is broken" into "no such user", which is the wrong answer to
give about someone's credentials.

7 tests, 6 verified red against the pre-fix code; the seventh is the
non-referral control that must stay green either way. Suite 257/0, 2 skipped.

Live-proven against the ZB NAM domain root before and after.
2026-08-12 21:27:05 -04:00
Joseph Doherty 846b77f5b4 feat(overview): show historian session-pool depths on the HistorianGateway card
Asked whether the gateway's new session row also covered HistorianGateway.
It did not, and could not: HistorianGateway publishes its pool depths on a
different TIER with a different KEY SET.

  mxaccessgw       active tier   total / ready / faulted        one check
  historiangw      READY  tier   warmSessions / pool / …        TWO checks

The session row is located by the total/ready/faulted triple, so it correctly
ignored these rather than half-matching them. This adds a sibling row instead
of unifying the two behind a shared shape, because there is no such shape -
inventing one would mean rendering a contract neither app publishes.

No poller change was needed: the ready tier's body is already retained, so
this is entirely a rendering change.

Labelled "Sessions pooled", deliberately not "connections". warmSessions is
pool DEPTH - warm pre-authenticated sessions held ready - and sessions are
leased on demand, so the event pool legitimately sits at 0 until something
reads events. Calling that a connection count would make a normal idle pool
read as an outage, so 0 is shown plainly and the row goes red only on
consecutiveFactoryFailures, which is an actual fault.

Pools render read-then-event rather than in dictionary order, so the line is
stable across polls and the pool an operator cares about comes first.

188 tests (183 + 5): ordering, that an idle pool is not painted red, that a
failing factory is, a positive control on the omission assertion, and one
pinning that neither app's row can render the other's data.
2026-08-12 05:16:25 -04:00
Joseph Doherty da276ff15a feat(overview): show MXAccess session counts on the gateway card
The gateway publishes its live MXAccess session counts, and the dashboard
could not reach them. Four things stood between the data and the card, and
only the last one is cosmetic:

The active tier was probed only for instances declared HasActiveRole. A
standalone gateway has no active/standby role, so its active tier was never
requested at all. The tempting fix is to declare mxgw HasActiveRole, and it
is wrong: that flag also paints an Active/Standby badge, so it would buy the
data by asserting a role that does not exist. The probe is now unconditional
for any reachable instance while ObserveActive stays role-gated, separating
"what does this tier report" from "am I the active half".

The active probe's parsed body was then discarded - only ready.Report was
kept - so InstanceSnapshot gains ActiveReport. The two tiers stay separate
rather than merged, because a check name is only unique within a tier.

The card's one data-rendering path, ClusterDataLine, is located by the Akka
leader/activeNode keys and would ignore session data even once present. The
new row follows that helper's own precedent and locates the check by the data
it carries - the total/ready/faulted triple - not by name, requiring all three
so a future check publishing a lone "total" cannot be mistaken for it.

Rendered on the card FACE, not inside the collapsed check list: a count behind
a disclosure triangle is one nobody reads. Zero is shown rather than hidden,
since a gateway holding no sessions is the interesting case and suppressing it
would make the row appear only when the news is good.

Cost, stated plainly: every reachable instance now makes one extra HTTP
request per poll. The unreachable-instance skip is untouched, so the
worst-case sweep duration - which is set by timeouts, not by healthy
round-trips - is unchanged. Four cadence tests were counting raw requests as a
proxy for "instances polled"; they now count ready-tier probes, which is what
they always meant and is robust to tier changes.

The Wonder registry comment claiming the active tier ran an empty check set
was true when written and stopped being true when the gateway added the
check; it now warns against the HasActiveRole shortcut instead.

183 tests pass (177 + 6), including a positive control on the absence
assertion so "row not rendered" cannot pass vacuously.
2026-08-12 04:47:06 -04:00
Joseph Doherty 81e0005628 docs(index): OtOpcUa on 0.6.2; the NuGet partial cached-index trap recurs per publish 2026-08-11 09:09:05 -04:00
Joseph Doherty b850c3a47f docs(index): Secrets 0.6.2 — rejection message teaches the container case 2026-08-11 09:04:55 -04:00
Joseph Doherty c5e894d9b3 feat(secrets): 0.6.2 — the content-root rejection message teaches the container case
Suggested by the OtOpcUa session, the only real containerized deployment in this family
and the one that hit the false positive. A store on a volume mounted inside the content
root is durable across container replacement but is rejected anyway, because the rule
cannot tell a mount from an ordinary directory. The message now says so, gives the fix,
and forecloses the wrong one by stating that no override exists.

A false positive's entire cost is the confusion in the moment, so an error that names its
own fix costs nothing on the true-positive path and turns the false positive into a
two-minute edit. Message only, no behaviour change.

Their case for keeping the rule strict is recorded in the CHANGELOG because it is better
than the trade-off I had written: the workaround is an improvement rather than a
concession, an override flag has the lifecycle of a knob set once and never revisited,
and mount detection would make the verdict depend on runtime platform state so the same
path would pass on one host and fail on another.
2026-08-11 09:04:02 -04:00
Joseph Doherty 74066bbe27 docs(secrets): record the container over-rejection and the OtOpcUa 0.6.1 adoption 2026-08-11 09:01:04 -04:00
Joseph Doherty 6084465e23 test(secrets): the positive control was a tautology propping up the negative one
Raised by the mxaccessgw session, which went back to its own tests after I reported a
vacuous assertion in mine and found the same class one step further from the fuse.

The rejecting test asserts no store file is left at a rejected path. That claim is only
meaningful if something proves the write path is live at all: "no file was created" is
indistinguishable from "nothing in this container ever creates files". The positive
control was supposed to establish that and did not -- it asserted Assert.NotNull on a
resolved SecretsSqliteConnectionFactory, which is close to a tautology once no exception
escaped, and it never ran the migration at all. So if the pre-host container ever stopped
touching the store, the rejecting test would have gone quietly vacuous while the positive
control kept passing. Neither would have failed.

The positive control now runs SqliteSecretsStoreMigrator.MigrateAsync and asserts the
database IS created. The pair is mutually checking: the migration writes the file when
allowed and does not when rejected, and neither assertion stands on its own.

Verified the same way as the last one, by simulating the failure rather than reasoning
about it: replacing the migration with a no-op makes the positive control fail with "the
accepted path must actually get a store file". Reverted after measuring.

No library change; 0.6.1 as published is unaffected. Suite 502 passing.
2026-08-11 08:56:46 -04:00
Joseph Doherty d6fe3ae62a test(secrets): the pre-host regression test was asserting the weaker claim, and vacuously
Two defects in the 0.6.1 regression test, the first raised by the mxaccessgw session
from its own adoption, the second exposed by acting on it.

Assertion order. The test asserted the throw before the artifact. That hides the
stronger finding: a regression that stops the throw but still creates the store fails
with "no exception was thrown" and never mentions the database sitting at the rejected
path -- which IS the defect. Now captures with Record.ExceptionAsync, asserts no file
created first, and asserts the exception type last. Notable because the defect under
test was itself "a boot outcome was observed instead of the artifact being probed", so
closing it with an outcome-first assertion would have repeated the mistake.

Vacuous assertions. Simulating the regression -- replacing the 4-argument call with the
3-argument one, which still compiles, exactly as the call-site comments warn -- showed
the test failing on the exception assertion rather than the file assertion. No file had
been created in EITHER case: the test resolved SecretsSqliteConnectionFactory, whose
constructor never touches the filesystem. The File.Exists assertions could not fail. The
test now resolves SqliteSecretsStoreMigrator and runs MigrateAsync, which is what a
pre-host expander actually does and what actually creates the database.

Verified by simulating the regression again: the test now fails with "a rejected path
must not be left holding a store file" rather than "no exception was thrown". Reverted
after measuring.

No library change; 0.6.1 as published is unaffected. Suite 502 passing.
2026-08-11 08:52:53 -04:00
Joseph Doherty 90b7cc6c48 docs(index): Secrets 0.6.1 — the pin alone does not close the pre-host gap; mxgw 0.6.0 pushed and needs a follow-up 2026-08-11 08:46:13 -04:00
Joseph Doherty 9b6afe3efd docs(index): Secrets 0.6.1 — close the pre-host hole in the store-path guard 2026-08-11 08:39:21 -04:00
Joseph Doherty cbfe296279 fix(secrets): close the pre-host hole in the store-path guard (0.6.1)
Found by the HistorianGateway adoption of 0.6.0, which probed the rejected paths
instead of observing a clean boot — a clean boot being equally consistent with the
validator not being wired at all.

An application that expands ${secret:} references before building its host composes
this subsystem in a throwaway ServiceCollection with no IHostEnvironment in it, then
migrates the store from that container. SecretsOptionsValidator resolves the content
root from IHostEnvironment and skips the under-content-root rule when it is absent, so
pre-host an absolute in-content-root path passed the only rule still applying, the
migrator CREATED the database, and the boot failed a second later once the real host
registered IHostEnvironment and the rule finally fired.

The observable result was a rejected boot that still left an empty store, with -wal and
-shm siblings, at the rejected path — the same artifact that made the MxGateway outage
read as "the database is there, it's just empty", which is precisely what this guard
exists to prevent. A relative path was unaffected because the absolute-path rule fires
with or without a content root; that asymmetry is what exposed it.

The mistake was conflating "no IHostEnvironment registered" with "no content root
exists". New AddZbSecrets overload takes the content root explicitly; the 3-argument
overload is unchanged and still falls back to IHostEnvironment, so this is additive.
SecretsOptionsValidator gains a string? constructor alongside the IHostEnvironment? one.

Reproduced first in an isolated harness before changing anything: a bare host rejects
both bad paths leaving no artifacts, and a bare ServiceCollection with no
IHostEnvironment migrates an in-content-root path to disk. Both are now regression tests,
the second paired with a positive control asserting the old behaviour still holds when no
content root is supplied — so the test is about the explicit content root rather than
about paths in general.

Also documents an upgrade note that applies to 0.6.0: a store seeded under the old
relative default is orphaned rather than migrated, and nothing signals it.
2026-08-11 08:37:53 -04:00
Joseph Doherty 105c230cb1 docs(index): Secrets 0.6.0 — fail-closed store-path validation, default moves outside the content root 2026-08-11 08:26:05 -04:00
Joseph Doherty 944595ad32 feat(secrets): fail-closed store-path validation; default moves outside the content root
Secrets:SqlitePath is now validated at startup by SecretsOptionsValidator using two
rules in the new public SecretsStorePathRules. Both come from production incidents and
neither implies the other.

Must be absolute: a relative value resolves against the process working directory,
which for a Windows service is C:\Windows\System32, so the store lands outside the
installation; in a dev loop it lands in the source tree (a gateway was observed writing
its secrets database into src/, tripping that repo's own tree-hygiene test).

Must not be inside the content root: an absolute path can still point into the
directory every deployment procedure in this family renames on upgrade. On 2026-08-09 a
gateway's credential store sat inside its Server\ directory; the deploy renamed Server
to Server.bak.*, the database went with it, and the process created a fresh empty one
at the same path. Every consumer lost its credential, silently, for two days. The
existing "must be absolute" convention did not help — the path was absolute.

The rules reject rather than relocate. Silently moving a credential store presents later
as an authentication failure pointing nowhere near the configuration that caused it; a
boot error is seen immediately by whoever caused it. Validation is deliberately not
exempted in Development: a guard that never runs in a dev loop or in CI rots, and the
configuration behind the outage looked entirely reasonable.

BREAKING for configuration, not API. SecretsOptions.SqlitePath now defaults to an
absolute per-user path under LocalApplicationData; it was "secrets.db", which the new
rules reject. An application configuring a relative path will fail to boot — remove the
key or set an absolute one outside the content root. All five deployed instances of this
family were checked first and already set an absolute path outside their content root,
so the migration edge (a host relying on the OLD default now finding nothing and
creating an empty store — this bug, re-introduced by its own fix) does not apply to any
of them.

Per-user rather than machine-wide is deliberate: CommonApplicationData is /usr/share on
Linux and macOS, which a normal user cannot write, so a machine-wide library default
would fail every consuming application's boot on a developer machine. An application may
compute its own default; the configured value always wins.

Validator registration is idempotent. AddZbSecrets is legitimately called more than once
in real compositions, and TryAddEnumerable cannot de-duplicate a factory-built
descriptor — it de-duplicates on implementation type, which a factory does not carry, so
it throws on the second call rather than skipping. The existing suite caught this.

Tests cover both rules including the segment-boundary case (/srv/app-data must not read
as inside /srv/app — a false positive on a fail-closed startup rule is an application
that will not boot), that the shipped default satisfies the rules it ships with, that
the default is not machine-wide, idempotent registration, and — most importantly — that
a bad path actually throws when IOptions is resolved, since a correctly implemented
validator that is never invoked is the same "guard that does not fire" failure this
change exists to prevent.

Family bumps to 0.6.0. Adds a dependency on ZB.MOM.WW.Configuration 0.1.0 for the shared
OptionsValidatorBase/ValidationBuilder vocabulary, which every consumer already
references.
2026-08-11 08:18:37 -04:00
Joseph Doherty f088cb81ba docs(index): ScadaBridge Central UI sweep merged + deployed to wonder (Theme 0.4.1 live) 2026-08-11 07:31:54 -04:00
Joseph Doherty 003783a593 docs(index): record ZB.MOM.WW.Overview — the hosted family dashboard, now deployed to wonder
This repo hosts one application besides its shared libraries, and the index did
not mention it at all. Adds what it is, that its registry ships empty by design,
and the two constraints that bit during the first real deployment: publish
self-contained (wonder has no .NET 10 runtime), and do not put co-located
instances on a shared host name, because leader-to-instance resolution matches on
host only and the first match wins the chip for every group.
2026-08-11 06:54:08 -04:00
Joseph Doherty 4f97e72ac9 fix(overview): wonder registry — 127.0.0.1 BaseUrls so leader names cannot resolve wrongly
Live on the box, the ScadaBridge *site* card claimed "Leader · central". Central
and site are separate Akka clusters, so that name was simply wrong.

Cause is in the registry, not the app. ResolveToInstanceName matches a reported
Akka leader address to an instance on HOST ONLY - correct by design, because an
app's Akka remoting port and its HTTP port differ, so comparing ports would never
match. It assumes what holds on the docker rig and not here: distinct hosts per
instance. All five instances are on one box, and the scan is fleet-wide in
registry order, so with every BaseUrl on "localhost" the first matching entry won
the chip for every group.

No host value makes this resolve CORRECTLY, because the instances really are
co-located. So make it never match instead: ScadaBridge's Akka addresses use host
"localhost" and OtOpcUa's uses the FQDN, and "127.0.0.1" is string-unequal to
both. Every chip now falls back to the raw Akka address - unambiguous and always
true. A raw address beats a confident wrong name.

Using the FQDN for OtOpcUa's BaseUrl would have resolved its chip correctly and
was rejected: that name resolves to a link-local IPv6 on this box, and routing
the real health probe through it to improve a label trades the primary function
for a cosmetic one.

ManagementUrl values are unchanged - they are followed by the operator's browser
from another machine and must keep the box address.
2026-08-11 06:50:27 -04:00
Joseph Doherty c582508ae5 feat(overview): wonder-app-vd03 registry overlay
Adds appsettings.Wonder.json for the first deployment of this dashboard to a
real box. Named "Wonder" rather than "Production", mirroring the existing
Docker overlay: this is ONE deployment's fleet, not a claim about what every
production deployment looks like.

Every port was established by probing the running box, not inferred from the
docker rig - and the two disagree, so inference would have been wrong:

  OtOpcUa             :9000  (AdminUI on the same listener)
  ScadaBridge Central :8085  (rig serves this on :5000)
  ScadaBridge Site    :8084  (no UI - / is 404, so the card carries no link)
  MxAccessGateway     :5130  (:5120 is gRPC)
  HistorianGateway    :5220  (:5221 is gRPC h2c)

:8083 and :8086 answer 400 to an HTTP/1.1 GET - h2c gRPC - and are excluded.

Both gateways are HasActiveRole:false. Their /health/active does return 200,
but only because the active tier runs an EMPTY check set when no Active-tagged
check is registered, so an Active badge would assert a role neither has.
Central and site are separate groups because they are separate Akka clusters;
one shared group would manufacture a leader disagreement.

BaseUrl is localhost (probed by the service, on the box) while ManagementUrl
carries the box address (followed by the operator's browser, elsewhere).

Serilog's file path is absolute and outside the Server directory an upgrade
replaces - a relative path resolves against the service AppDirectory, so every
upgrade would silently eat the log history. Same class of defect that cost
HistorianGateway its secrets store on a swap.

Boot-verified locally under ASPNETCORE_ENVIRONMENT=Wonder: registry passes
OverviewOptionsValidator and the host starts.
2026-08-11 06:44:17 -04:00
Joseph Doherty 8f31184b7d chore(overview): bump Theme 0.3.1 -> 0.4.1, Health 0.2.0 -> 0.3.0
Family alignment ahead of the first wonder-app-vd03 deploy. Both bumps are
inert for this app, established rather than assumed:

- Theme 0.3.1 -> 0.4.1 is two commits: the upstreamed Bootstrap .btn sizing
  block and the rail-btn-block modifier. Overview answers NO to both of the
  questions the kit README says to ask - it declares no .btn sizing of its own
  and has ZERO call sites carrying a bare `btn` token (its single button is
  class="rail-btn"), so the new .btn rule matches nothing here. The .rail-btn
  refactor that introduced --rail-btn-inset resolves to the same 0.6rem the
  literal margin used, so the one call site is unchanged. Same answer as
  HistorianGateway. Note a naive \bbtn\b grep is a FALSE POSITIVE on
  "rail-btn" - the hyphen is a word boundary; match a whitespace-delimited
  token instead.

- Health 0.2.0 -> 0.3.0 is a pure version-number alignment: the core
  ZB.MOM.WW.Health package is byte-identical between the two, with the entire
  delta confined to ZB.MOM.WW.Health.Akka (ActiveNodeHealthCheck,
  ClusterActiveNode, AkkaActiveNodeGate), which this app does not reference.
  Verified with a positive control on the diff path. The 0.2.1 active-tier
  503 change therefore cannot reach this app's own endpoints; it registers no
  Active-tagged check, so /health/active runs an empty set and stays 200.

Overview consumes the 0.3.0 `activeNode` data key over the WIRE from other
apps' health JSON, which is independent of the package it compiles against -
LeaderResolver already ranked it (344bdc4) while pinned to 0.2.0.

Release build 0 warnings; 177/177 tests pass. All remaining outdated packages
are test-only (bunit, coverlet, test SDK); nothing the app ships is behind.
2026-08-11 06:35:56 -04:00
Joseph Doherty 8e99b3b4c0 docs(playbook): re-read comments inside your own diff; check modals for state of their own
A commit that removed a modal's self-closing behaviour shipped two comments in the
same file still describing it as self-closing — review checks whether the code is
right, not whether the surrounding prose survived. And the property that predicts
which modals break on refresh is 'holds no state of its own' (pure projection of a
list), not the presence of a detail field.
2026-08-11 06:18:00 -04:00
Joseph Doherty 7926e8bb46 docs(playbook): a limitations section lends unearned credibility to the claims above it
Readers take 'what I could not establish' as evidence the rest was held to that
standard. Write the claim the evidence licenses, not the broader one; and when two
items in your own not-established list contradict each other, flag it — that
contradiction is the strongest lead you have, not another unknown.
2026-08-11 05:59:59 -04:00
Joseph Doherty 76098ffcd4 docs(playbook): keyword grep is blind to unlabeled entropy — the reliable check is your own minted values
A bare 32-hex key id matches none of the six credential keywords (verified). Added
an entropy scan and a PEM check as generic complements, marked the prefix list
repo-specific, and made the primary rule explicit: a gate that mints anything must
grep the commit for the literal values it produced.
2026-08-11 05:58:07 -04:00
Joseph Doherty 1cc4ccd258 docs(playbook): scan commit content too, and record which repos lack a .claude/ ignore
A filename audit finds the wrong-file problem; it cannot find a credential pasted
into a legitimately-tracked doc. Both checks are cheap and catch disjoint failures.
Verified: .claude/ is gitignored in OtOpcUa and HistorianGateway, NOT in mxgw or
ScadaBridge — in those two, enumerate-first discipline is the only guard.
2026-08-11 05:54:41 -04:00
Joseph Doherty 20e16c934c docs(index): Theme 0.4.1 — all five consumers pushed; two on branches, ScadaBridge's not deploy-ready 2026-08-11 05:52:30 -04:00
Joseph Doherty ec4ad984c1 docs(playbook): enumerate untracked paths before staging a sweep commit
A sweep's landing commit is where unrelated local state gets swept in. One repo's
'78 modified' was 76 modified + 2 untracked, one of which was .claude/ holding
settings.local.json — a literal 'git add -A' would have put permission config into
a tracked commit feeding a production deploy, invisible in a 76-file diff.
2026-08-11 05:51:21 -04:00
Joseph Doherty 094307e18b docs(playbook): test the shared premise when all hypotheses die; eliminate at the right granularity
Two deadlocked investigations both inherited 'file exists => sink constructed =>
no events flowed'; the pinned sink version creates no file until the first emitted
event, so the artifact proved the opposite. And 'a second log wrote in the same
directory' rules out directory-level failure, not per-handle failure — a proof
about the container is not a proof about the member.
2026-08-11 05:12:31 -04:00
Joseph Doherty baaf0a183c docs: correct the correction — absence of a .btn block does not imply the bump restyles
HistorianGateway has no local block AND no Bootstrap button call sites (all 15
buttons use the kit's .rail-btn chassis class), so the kit's .btn rule matches
nothing and bumping it changes nothing visible. My previous correction claimed the
opposite. Checking this needs two greps — declaration AND call sites — which come
apart exactly when an app doesn't use Bootstrap buttons.
2026-08-11 04:18:20 -04:00
Joseph Doherty dc6410dfad docs(playbook): name the recurring failure — a set-wide claim from a partial check
Three instances in one round (btn-block universality, sweep behavior-preservation,
the mxgw Bootstrap exemption), all the same shape, all caught by the asserter
re-checking rather than by challenge. Fix is a cheap per-member check that runs,
or an honestly-scoped claim when it hasn't.
2026-08-11 04:15:10 -04:00
Joseph Doherty 3777e50564 docs(theme): correct the .btn upstreaming claim — it was not universal
HistorianGateway has no local .btn sizing in either its committed tree or its
sweep branch (only vendored bootstrap.min.css), so the shipped comment and README
naming all five consumers were wrong. Consequence worth stating: HG's bump to
0.4.0+ is a VISIBLE change (buttons shrink to .85rem), not the no-op cleanup it is
for consumers that already carried the block.
2026-08-11 04:12:34 -04:00
Joseph Doherty 40e07aa08e docs(theme): correct the --rail-btn-inset comment — it reduces the duplication, it does not remove it
The prior wording claimed the two rules 'cannot drift apart', which is only true
for the documented composition. 0.6rem still appears twice; the fallback confines
a stale copy to the undocumented modifier-alone path. Records why hoisting the
var to :root would be worse rather than better.
2026-08-11 03:22:24 -04:00
Joseph Doherty 9dd288b3ad docs(playbook): three caches not one — confirm against server output; mxgw is the check-first outlier 2026-08-11 03:21:14 -04:00
Joseph Doherty f313c5e62e refactor(theme): rail-btn inset as --rail-btn-inset so .rail-btn and .rail-btn-block cannot drift
Unreleased — behaviourally identical to the published 0.4.1 (browser-verified:
composed <a> and <button> both fill the rail foot exactly, 0.00px short). The
var() carries a 0.6rem fallback because --rail-btn-inset is declared on .rail-btn,
so rail-btn-block used alone would otherwise have an undefined var, invalidating
the whole width declaration at computed-value time and silently reverting to
width:auto — the exact <button> shrink-wrap bug 0.4.1 fixed.
2026-08-11 03:20:37 -04:00
Joseph Doherty f9d4e2f514 docs(index): Theme 0.4.0/0.4.1 — .btn sizing upstreamed, rail-btn-block fixed, 5 consumers 2026-08-11 03:18:25 -04:00
Joseph Doherty d603a2f66e docs(playbook): cache-bypass on the live gate + trim-don't-delete on upstreamed blocks
Two lessons from the Theme 0.4.0 rollout across five apps.

Live gate: after a kit-CSS change a normal reload can serve the cached previous
layout.css while the server serves the new one. .btn then computes at
Bootstrap's 16px — the exact signature of a failed upstreaming — so the natural
response is to restore the local rule just deleted, entrenching the duplication
the change removed. Hard-reload before trusting any computed-style probe.

Upstreaming: the kit ships sizing only, so trim the local .btn rather than
deleting it. mxgw's block also carried border-radius/font-weight/white-space,
which a wholesale delete would have dropped silently; three of five apps' blocks
were pure sizing and safe to delete outright, and the difference is invisible
without diffing. Also records why a retained border-radius must stay a literal.

Marks the .btn block as upstreamed in 0.4.0 rather than a candidate.
2026-08-11 03:02:17 -04:00
Joseph Doherty 49fbbcfaeb fix(theme): rail-btn-block must use an explicit width (0.4.1)
0.4.0's rail-btn-block used display:block + width:auto, which fills for an <a>
but SHRINK-WRAPS a <button> — a form control does not take the fill-available
behaviour a non-replaced block box gets. Measured in one 197px rail-foot
container: <a> filled to 177.42px (0 short), <button> came up 114px short.

That matters because a rail foot normally holds both element types: Sign In is
an anchor, Sign Out is a form-submit button. So 0.4.0's modifier got one right
and one wrong, and the wrong one is what signed-in operators see — worse than
the width:100% overflow it was meant to replace (~10px of visible clipping).

Fixed with an explicit calc(100% - 1.2rem) + box-sizing:border-box, which
measures 0px short for both element types. Both rejected shorthands and their
measured failures are recorded in the CSS so neither is reintroduced as a
'simplification'.

Found by HistorianGateway while evaluating adoption; it held off adopting
rather than trading one defect for a larger one. No consumer had adopted the
modifier, so nothing shipped broken. The .btn half of 0.4.0 is unaffected and
is already live-verified in three apps.

Build 0 errors, 48/48 tests.
2026-08-11 03:01:15 -04:00
Joseph Doherty e7a126a9fc feat(theme): upstream the Bootstrap .btn sizing block into the kit (0.4.0)
Bootstrap hard-codes --bs-btn-font-size: 1rem, oversized against the kit's
0.9rem body. All five consuming apps had independently written the identical
block into their own stylesheets (ignitionoee app.css, OtOpcUa site.css, mxgw
site.css, HistorianGateway site.css, ScadaBridge site.css), each carrying a
'delete this when the kit ships a .btn rule' comment. This is that release.

Sized by CSS-variable override only, never by redeclaring box properties:
Bootstrap's .btn-group seam/radius machinery reads the same variables, so a
literal font-size at equal specificity flattens .btn-sm into a padding-only
difference. That was a real defect in mxgw's local copy, so the rationale is
recorded in the CSS to stop it being 'simplified' back.

Lands in layout.css, which ThemeHead emits after theme.css and both after
Bootstrap, so the override wins on source order at equal specificity.

Ships in the same 0.4.0 release as rail-btn-block. Consumers get the sizing on
bump (not opt-in, unlike rail-btn-block) and should delete their local copies
in the same change. Build 0 errors, 48/48 tests, packed asset verified to carry
.btn, .btn-sm/.btn-group-sm and rail-btn-block with no literal font-size.
2026-08-11 02:17:16 -04:00
Joseph Doherty 5fc75d93fd feat(theme): rail-btn-block full-width rail-footer modifier (0.4.0)
HistorianGateway hand-rolled a .rail-btn override purely to make the rail-foot
sign-out button span the rail; its own comment flagged folding it into the kit.
Adds a composable modifier instead: class="rail-btn rail-btn-block".

Uses display:block + width:auto, NOT width:100%. The hand-rolled overrides set
width:100%, which resolves against the containing block and then adds .rail-btn's
0 0.6rem side margins on top, overflowing the rail by 1.2rem. width:auto fills
the same inset correctly.

Scope note: the app overrides that motivated this do more than full-width (they
also restyle font-size, padding, border, background and hover). Adopting the
modifier removes the width hack; whether to also drop the restyle is each app's
call, since it changes their rail appearance.

Version 0.3.1 -> 0.4.0 (additive). Build 0 errors, 48/48 tests, nupkg verified
to carry the new rule in staticwebassets/css/layout.css. Not yet published.
2026-08-11 02:13:37 -04:00
Joseph Doherty 3b7dbfa082 docs: correct mxgw Bootstrap claim + fold five-app sweep findings into admin_ui_cleanup
CLAUDE.md (Secrets row):
- mxgw is NOT Bootstrap-free (libman.json pins bootstrap@5.3.3, App.razor:7
  links it ahead of ThemeHead). The scadaproj#2 modal gate had skipped mxgw on
  that false premise; gate since run and PASS 2026-08-11.
- scoped-CSS bundle claim scoped to its 2026-07-19 date; OtOpcUa links one now
  too, so it is two of four rather than one.

admin_ui_cleanup.md — five rounds now (adds mxgw, HistorianGateway, ScadaBridge):
- 1a-1: test sources are a fifth definition site, checked BEFORE the ghost list.
  A class matched only by a test is a selector, never a ghost. Extends to
  substring and visible-text assertions, so button labels are load-bearing.
- 1a-4: two inverted button-sizing instances (literal font-size neutering
  btn-sm app-wide; a chassis class standing in for the button system).
- 1a-5: determine dark scheme per app; where one exists the step inverts.
- 1a-6 (new): a token override emitted as an inline style on the shell root
  defeats every scheme-level :root override. OtOpcUa carries the inert-but-
  latent instance.
- 1c: reword nothing before checking test sources; the docs may be the wrong
  document, not the page.
- 2: btn-sm fold breaks button.btn-*.btn-sm locators; cell-clip is wrong for
  resizable columns; briefs carry the rubric, not just line numbers.
- verification: baseline pre-existing failures by measuring; a suspiciously
  fast green is a vacuous pass, not a pass.
- live gate: mandatory bUnit or not; hit-testability over visibility; measure
  behaviour where computed values mislead (-webkit-box serializes flow-root);
  record what could not be exercised.
- new: exemptions from a family-wide sweep must re-derive their premise.
2026-08-11 02:07:01 -04:00
Joseph Doherty d131416673 docs: admin_ui_cleanup — add density/layout scan (1d) + fixes from the OtOpcUa /hosts rework 2026-08-10 17:41:36 -04:00
Joseph Doherty f0f607ea46 docs: admin_ui_cleanup.md — reusable admin-UI sweep playbook (from the ignitionoee router + OtOpcUa AdminUI rounds) 2026-08-10 17:09:00 -04:00
Joseph Doherty 2a38b6ac76 chore(plans): mark LDAP failover tasks complete 2026-08-10 16:43:50 -04:00
Joseph Doherty 75648ea28b docs(index): Auth 0.2.0 — LDAP sticky backup-DC failover published 2026-08-10 16:43:04 -04:00
Joseph Doherty 84af475683 feat(auth): LDAP backup-DC sticky failover — family 0.2.0 2026-08-10 16:41:18 -04:00
Joseph Doherty 3ce9cc3657 chore(auth): bump family version to 0.2.0 2026-08-10 16:41:18 -04:00
Joseph Doherty 1c675e9153 test(ldap): env-gated failover integration test vs live GLAuth 2026-08-10 16:40:59 -04:00
Joseph Doherty 92ff6a0d8c feat(ldap): failover observability — warn per hop, info on sticky change 2026-08-10 16:38:38 -04:00
Joseph Doherty 174ad952dc feat(ldap): endpoint walk with sticky-preference failover in LdapAuthService 2026-08-10 16:37:14 -04:00
Joseph Doherty 0a8fe68d0a test(ldap): sequence connection factory for failover tests 2026-08-10 16:33:32 -04:00
Joseph Doherty 8997a46b74 feat(ldap): FallbackServers option + boot-time validation 2026-08-10 16:33:32 -04:00
Joseph Doherty 5fbf53601c feat(ldap): LdapEndpoint + FallbackServers entry parser 2026-08-10 16:32:27 -04:00
Joseph Doherty 0c1702acbc docs(plans): LDAP backup-DC failover implementation plan (8 tasks, Auth 0.2.0) 2026-08-10 16:28:49 -04:00
Joseph Doherty 2dc919e8a4 docs(ldap): NAM AD setup notes + live TLS probe results; backup-DC failover design (Auth 0.2.0) 2026-08-10 16:22:31 -04:00
Joseph Doherty 95865f0e9b docs(index): OtOpcUa — tracker zeroed via #549–#559 authoring-parity arc (2 served-behaviour fixes: MQTT whitespace blobs, OpcUaClient legacy NodeId); R2-10 connect-path resilience; plan-task sweep; master pushed, origin back in sync at d06e92c6 2026-08-10 05:33:29 -04:00
Joseph Doherty 2f96709341 docs(index): ScadaBridge#34 FIXED — PID-1 crash wedge root-caused (SIGABRT ignored for PID 1); handler + init:true, live-verified
Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-08 05:24:20 -04:00
Joseph Doherty 46523db2bd docs(secrets): close scadaproj#4 — central shared SQL store + failover shipped
Program closeout: scadaproj#4 CLOSED (comment issuecomment-5751) — ScadaBridge's
central pair now runs ONE shared SQL-Server store in Grpc mode (0.5.0
FallbackEndpoints, 0.5.1 virgin-DB migrator race fix; ScadaBridge @ e697477c),
live-gated PASS 5/5 + re-drill. The pre-Serilog container-wedge defect the gate
reproduced twice is filed as ScadaBridge#34 (pre-existing, out of program scope).

- clustered-secrets.md: central pair = one shared SQL store (connstr literal/env,
  never ${secret:}); rewrap = ONE central run + both nodes of each site pair;
  FallbackEndpoints same-store-only rule; 0.5.1 minimum for central pairs
- components/secrets/GAPS.md: resolution section appended; stale wait-on-#4 struck
- CLAUDE.md Secrets row: #4 CLOSED, family 0.5.1, gate + residual recorded
- tasks.json: all 6 tasks completed

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 11:43:53 -04:00
Joseph Doherty 31ca9407a6 fix(secrets-sqlserver): retry the virgin-DB concurrent migrator race; release family 0.5.1
The ScadaBridge central shared-store live gate proved SqlServerSecretsStoreMigrator's
"safe to run concurrently" claim false on a virgin database: Serializable isolation does
not serialize the IF NOT EXISTS metadata probes against another session's in-flight
CREATE, so of two central nodes booting together the loser died with SqlException 2714
("There is already an object named 'zbsecrets'") — the retry filter covered only
deadlock 1205. Losing such a race means the object now exists (the desired end state),
so 2714 (schema/table), 1913 (index) and 2627 (schema_version MERGE-insert PK) are now
retryable alongside 1205; the retry re-runs the idempotent IF NOT EXISTS path.
Classification scans the whole SqlException.Errors collection (2714 arrives stacked with
2759), the retry cap keeps genuine conflicts failing closed, and 2705 is deliberately
excluded (unreachable — columns live in a single CREATE TABLE statement). Predicate
extracted as an internal static pinned by offline tests; live suite gains an env-gated
4-concurrent-migrators virgin-database test. Six packages pushed to the Gitea feed at
0.5.1.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 11:35:13 -04:00
Joseph Doherty e62b4a5baf chore(secrets): release family 0.5.0 (FallbackEndpoints hub failover)
Bump ZB.MOM.WW.Secrets family 0.4.1 -> 0.5.0 and date the CHANGELOG
entry. All 6 packages (Abstractions, Secrets, Replicator.SqlServer,
Replicator.AkkaDotNet, Replicator.Grpc, Ui) packed and pushed to the
dohertj2-gitea feed; restore-verified from a scratch consumer with a
fresh package cache. Suite 470 passed / 0 failed / 15 skipped.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 09:51:52 -04:00
Joseph Doherty 7a2980e2f1 fix(grpc): keep the RpcException off the failover warning so no sink can render Status.Detail
Review follow-ups: the warning now carries only the two endpoint URIs and the
status code — attaching the exception object would let any real sink render
its ToString(), which for RpcException includes server-authored Status.Detail.
The leak pin test now also asserts no exception rides on the warning, via a
new WarningExceptions capture on RecordingLogger. Plus two cosmetic nits:
unified ThrowIfNull idiom, documented that FallbackEndpoints mutation after
Validate is unsupported.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 09:49:45 -04:00
Joseph Doherty 0d4978953f feat(secrets-grpc): FallbackEndpoints + sticky failover hub reader (scadaproj#4)
SecretsGrpcHubClientOptions gains a getter-only FallbackEndpoints list:
additional hub addresses tried in order when a call fails with a
transport-level RpcException. Validation fails startup on blank/relative
entries and on any duplicate of the primary or another fallback (a
duplicated endpoint silently halves the configured failover).

New FailoverSecretsHubReader composes one GrpcSecretsHubClient per
endpoint: the answering endpoint is sticky (a sweep is GetManifest + N
GetSecrets batches — without stickiness every call after a primary
outage re-pays a full CallDeadline before reaching the healthy
fallback), rotation wraps so a recovered primary is retried when the
stuck-to endpoint fails, only RpcException triggers failover
(cancellation and defects propagate untouched), and when every endpoint
fails the last RpcException is rethrown so the sweep degrades to
last-known-good exactly as today. Failover warnings name only the two
endpoint URIs and the status code — never any credential material.

DI: zero fallbacks keeps the registration graph byte-identical to 0.4.x
(single keyed channel under ChannelServiceKey, plain
GrpcSecretsHubClient); with fallbacks, one container-owned keyed channel
per endpoint (fallback i under "{ChannelServiceKey}:fallback:{i}") wired
into the failover reader. GrpcSecretsHubClient itself is unchanged.

Safe only when every listed endpoint serves the SAME store — for
ScadaBridge, the central pair over one shared SQL Server store; the
options doc and CHANGELOG carry the warning.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 09:37:22 -04:00
Joseph Doherty 7df05ccc27 docs(plans): central shared SQL secrets store + hub endpoint failover (scadaproj#4)
Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 09:27:28 -04:00
Joseph Doherty 294eb163cd docs(glauth): keep the verify ldapsearch continuation intact after the SEC-36 comment scrub 2026-08-07 09:18:47 -04:00
Joseph Doherty aada53b27a sec(glauth): rotate serviceaccount passsha256; scrub retired plaintext from comments (mxaccessgw SEC-36) 2026-08-07 09:18:05 -04:00
Joseph Doherty 5198d3dc7f docs(secrets): close out scadaproj#3 — gRPC hub shipped 0.4.1, both live gates PASS; residual filed as #4
Task 9 (closeout) of the Secrets gRPC-hub program. Bookkeeping only; no code.

- clustered-secrets.md, Production enablement: the gRPC hub is no longer
  pending. It is BUILT, SHIPPED (0.4.1) and LIVE-GATED PASS 4/4 (ScadaBridge
  main @ f6c3f7c5, docs/plans/2026-08-07-secrets-grpc-hub-live-gate.md), so the
  "until that ships, ScadaBridge replication stays off" line is replaced with
  the truth: the code path is merged and gated, and production enablement is a
  separate operator action behind a still-default-off flag. OtOpcUa's
  pair-local topology is recorded as live-gated (lmxopcua master @ 1bd79c8e)
  rather than pending re-gate. Rotation fan-out corrected: on ScadaBridge it is
  BOTH central nodes plus both nodes of every site pair, because each central
  node has its own independent store.

- components/secrets/GAPS.md: new "gRPC hub delivered" section recording the
  0.4.0/0.4.1 publish, both gates with SHAs and gate-doc paths, and the
  residual. Existing narrative left intact and amended, not rewritten.

- CLAUDE.md Secrets row: lib version 0.3.0 -> 0.4.1 and the app-pin claim
  corrected (ScadaBridge pins 0.4.1 for the Grpc replicator; the other three
  still pin 0.2.3); the "production topologies DECIDED" region now records
  delivery, both gates, default-off, and the residual.

- Plan ledger: task 9 completed.

Residual carried forward as scadaproj#4 — ScadaBridge's central pair does not
converge with itself (central-b served an authenticated but EMPTY manifest all
gate while central-a held every secret) and the site client dials a single
endpoint; these are one design question, since failover to an empty hub would
succeed and silently stop convergence. scadaproj#3 is closed.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 09:00:11 -04:00
Joseph Doherty c86cead5c2 fix(secrets): rate-limited denial warning on the Grpc hub (live-gate finding) — 0.4.1
The ScadaBridge live gate (check 4) found SecretsHubAuthInterceptor denying
correctly but logging nothing: the only trace of a refusal was a framework
Grpc.AspNetCore.Server Information line. A follower whose bearer token was
mis-rotated therefore stopped converging silently, with the hub showing it
only at INF.

Every denial is now counted and summarised in a Warning emitted on the first
denial after startup or after a 60-second quiet window, carrying the denials
since the previous summary plus a breakdown by cause. A single probe is
visible immediately; a sustained flood is bounded to one line per window,
which is what makes warning safe at all — the endpoint is unauthenticated by
construction, so a per-denial warning would be an unbounded log write driven
by an unauthenticated caller. Counters are Interlocked and the emit is
decided by a compare-exchange on the last-emit timestamp, so exactly one
thread emits per window and a denial counted after the drain carries into
the next summary rather than being lost.

The cause breakdown is server-side diagnostics only. Denied() is untouched:
every rejection still returns the identical uniform Unauthenticated status,
the comparison is still constant-time, and no token material appears in any
log line. The existing warn-once-on-unconfigured-token signal is unchanged
and still emitted exactly once; denials in that state count toward the new
summary's "unconfigured" category.

TimeProvider is an optional default-valued parameter rather than a second
overload — the type must keep exactly one public constructor or the gRPC
interceptor activator silently stops invoking the auth gate.

Two existing tests scoped their assertions to the configuration warning,
since both kinds now share a category: the new line is deliberate behavior,
not drift.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 08:26:49 -04:00
Joseph Doherty 321ab22111 chore(secrets): 0.4.0 — ship ZB.MOM.WW.Secrets.Replicator.Grpc (pull-only central hub)
Bumps the ZB.MOM.WW.Secrets family from 0.3.0 to 0.4.0 and adds the new
ZB.MOM.WW.Secrets.Replicator.Grpc package to the packable set. Publishes
all six 0.4.0 nupkgs to the dohertj2-gitea feed and restore-verifies the
new package resolves from it in a fresh --packages directory. Existing
packages are behaviorally unchanged — no breaking changes.

Adds ZB.MOM.WW.Secrets/CHANGELOG.md (none existed previously) to record
this and prior releases, and lists the new package in README.md's
Packages table. Also includes the controller's pending ledger updates
for docs/plans/2026-08-07-secrets-grpc-hub-implementation.md (Tasks
1-4 and 8 marked completed).

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 06:57:30 -04:00
Joseph Doherty 5f81e65684 fix(secrets): route the unset-token harness through the real hub composition (review drift-risk)
An internal validateEagerly seam on AddZbSecretsGrpcHub replaces the harness's
hand-copied registration fragment, so the deny-all second-layer tests exercise
the production wiring and cannot drift from it.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 06:52:26 -04:00
Joseph Doherty 3e3748b985 test(secrets): Grpc hub end-to-end integration suite + pull-only contract pin
Adds the end-to-end layer the unit suites structurally cannot reach: a real
in-process ASP.NET Core host serving SecretsHubService through
AddZbSecretsGrpcHub/MapZbSecretsHub, a follower built by the shipped
AddZbSecretsGrpcHubClient, a real gRPC call between them, and real SQLite
stores on both sides. The class of defect this catches is pieces that are each
individually correct and are never connected to one another — for instance the
interceptor's warn-once, which only holds if the container really hands gRPC
the singleton it registered.

Covered: byte-identical convergence over the wire (every ciphertext/nonce/tag/
wrapped-DEK byte, kek_id, revision, both timestamps INCLUDING their offsets,
across a tombstone, a nulls-everywhere row and an empty-string-description row);
delete propagation; a hub unreachable at follower boot leaving the last-known-
good store intact and converging once it answers; the auth negatives fail-closed
across the wire with one uniform denial detail; the per-request name cap as
ResourceExhausted; and an RpcException from the call invoker escaping the hub
client unchanged, so a transport fault stays distinguishable from a parse fault.

The credential-hygiene assertions are made against logs captured at Trace on
BOTH hosts, so "no token material ever reaches a sink" is asserted at the most
verbose setting a deployment could switch on.

SecretsHubContractPinTests reads the generated descriptor — not the .proto text
— and pins the RPC set to exactly {GetManifest, GetSecrets}, plus unary-only and
the package-qualified service name. The hub is pull-only by construction:
updates originate at central only, and the absence of a write RPC is what
enforces that, not authorization a mis-wired follower may hold more of than
intended. A third RPC silently retires the guarantee, so the failure message
says so.

Microsoft.AspNetCore.TestHost pinned at 10.0.7 — the version ZB.MOM.WW.LocalDb,
OtOpcUa and ScadaBridge already pin, matching the Microsoft.Extensions.* line.

Full suite: 436 passed / 0 failed / 15 skipped, no new warnings.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 06:44:13 -04:00
Joseph Doherty 55e0178d5c merge(secrets): Task 3 client half — pull-only sweep + per-row parse isolation
Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 06:32:04 -04:00
Joseph Doherty 1c31e6bcb8 fix(secrets): Grpc hub client — per-row parse isolation (review Critical) + real-client CallInvoker tests
A single malformed row or manifest entry poisoned the whole sweep, permanently.
WireToDomain.ToRows/ToManifest materialized eagerly, so one unparseable element
threw out of the fetch callback, past SecretReplicationReconciler's per-batch
handling, into SweepSafelyAsync's whole-sweep catch. The follower's pull set is
derived from the hub's manifest, so the identical bad element arrived in the
identical batch on every interval and nothing ever converged — logged as "sync
failed", indistinguishable from a hub outage.

Isolation now matches the Akka sibling's split exactly: WireToDomain stays a
strict per-item parser and loses its two batch entry points (their absence is
pinned by a reflection test), while GrpcSecretsHubClient converts each item
inside its own try — the same shape as SecretReplicationActor.Materialize.
A dropped item costs one warning naming the secret and a reason category, and
every well-formed sibling still converges. Only parse-shaped exceptions are
caught (ArgumentException, FormatException); a defect still propagates. A row
whose own name is unparseable is logged under a marker rather than echoing the
untrusted string, and no ciphertext, DEK or credential reaches a log line.

GrpcSecretsHubClient had zero coverage — the existing fake implements the
ISecretsHubReader seam directly, bypassing the header, the deadline and the
conversion, which are the only things that class does. It is now driven for
real through a fake CallInvoker handed to the generated client.

The stale doc comment claiming the reconciler isolated the failure is replaced
by one describing the mechanism that actually exists, and Endpoint gains a note
that a plain-http hub sends the bearer token cleartext (doc only, no validation
change).

Tests 52 -> 67 in the package suite; solution green, no new warnings.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 06:29:51 -04:00
Joseph Doherty 353af72265 fix(secrets): Grpc hub server review follow-ups — GetSecrets batch cap, DI single-registration guard + tests
Five review items on the Task 2 server half.

1. GetSecrets now enforces a server-side cap on request.Names, refusing an
   over-cap batch with ResourceExhausted BEFORE any store read runs. The
   well-behaved follower chunks at 500, but client discipline is not a server
   defence — the family precedent (HistorianGateway's max_values) is that the
   server declines regardless. The new SecretsGrpcHubServerOptions.
   MaxNamesPerRequest defaults to 1000, comfortably above that chunk so a
   compliant sweep never meets it, and Validate() refuses a non-positive value
   at startup rather than letting it read at runtime as a broken follower. The
   refusal states the cap and the received count — neither is secret, and an
   operator cannot resize a batch without them — and never a name. The cap sits
   behind the interceptor, so it is defence in depth against a misbehaving
   token holder, not an anonymous-DoS control.

2. AddZbSecretsGrpcHub now refuses a second registration. The two calls do not
   compose: options binding MERGES (a key absent from the second section leaves
   the first section's value standing) while the SectionPath stamp is
   last-one-wins, so a hub registered twice could serve a token bound from one
   section while every failure message named the other. Detected via a private
   marker registration. The extension also gains real DI coverage — the intended
   single-call path asserted for token/SectionPath coherence through a built
   provider, a custom section path stamped end to end, a missing token throwing
   from the registration call itself, and the duplicate call throwing.

3. Client-streaming and duplex-streaming denial tests, so all four gated handler
   shapes are pinned rather than only unary and server-streaming, plus a
   valid-token test that reaches all three streaming continuations.

4. A cancellation test: GetSecrets hands the ServerCallContext token through to
   the store, pinned against a fake that records it.

5. The proto's service comment stated the ISecretReplicationHub mapping in prose
   that no longer matched the RPC name; it now says GetManifestAsync ->
   GetManifest and GetManyAsync -> GetSecrets explicitly. Comment-only — no
   message or rpc definition is touched. The GetSecrets rpc comment also notes
   the new RESOURCE_EXHAUSTED cap, which a client author has to know about.

Grpc server suite 50 -> 73 tests; full solution suite green, 0 new warnings.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 06:27:16 -04:00
Joseph Doherty c5ea3a7b59 feat(secrets): Grpc hub client — pull-only sweep service + options + DI
Client half of the central-hosted secrets hub: a site node follows central and
never pushes.

- `ISecretsHubReader` + `GrpcSecretsHubClient` — the read half of the hub as a
  follower sees it (manifest + bulk fetch, nothing else). Bearer credential and a
  per-call deadline are attached per call; responses convert through
  `WireToDomain`. Faults are deliberately not caught here, so an unreachable hub
  can never be mistaken for an empty one.
- `WireToDomain` — strict, per-row proto -> domain parse mirroring the Akka
  replicator's `SecretRowDto`: a name the domain would reject, a content type
  naming no enum member, or a non-round-trip timestamp is refused at the boundary.
  Explicit proto3 presence keeps null distinguishable from empty.
- `GrpcSecretSyncService` — `SqlServerSecretSyncService` with the push half
  removed. One `ReconcileAsync` per tick (pull-only by the reconciler's own
  contract, and batched, so a cold-start pull set cannot exceed gRPC's 4 MB cap),
  never throws out of `ExecuteAsync`, warns once and retries on the next interval.
  The local store is left completely undecorated — the sweep is its only hub-ward
  writer.
- `SecretsGrpcHubClientOptions` — fail-closed `Validate()` naming the exact
  configuration key, including the section a caller actually bound. The bearer
  token is never echoed by any message.
- `AddZbSecretsGrpcHubClient` — binds, eagerly validates, and registers the
  channel under a service KEY so it cannot lose a `TryAdd` race to an
  application's own `GrpcChannel` and dial the wrong endpoint with the hub
  credential attached.

Tests 52/52 (red-first), including a source-scan guard pinning that no client file
names `ComputePushSet`, `ReadLocalAsync`, or `ApplyReplicatedAsync`, and a
reflection pin that the reader seam exposes exactly two read operations.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 06:12:03 -04:00
Joseph Doherty 7fc77f2790 feat(secrets): Grpc hub server — SecretsHubService + fail-closed bearer interceptor + DI
The server half of the central-hosted pull-only secrets hub. SecretsHubService
adapts the node's own ISecretStore onto secrets_hub.v1 using exactly two read
members (GetManifestAsync, GetAsync) — the proto exposes no write RPC, so a
follower has no path to put a row into central whatever its credentials allow.

GetSecrets omits a name the hub does not hold and skips one that will not parse
as a SecretName; neither is an error, because both describe a follower acting on
a manifest that was true a moment ago. Failing the call would stall the sweep and
let one bad name deny the follower every other row in the batch. Names are
re-validated server-side (the wire type is a plain string) and de-duplicated on
the normalized value.

DomainToWire mirrors the Akka replicator's SecretRowDto discipline exactly:
round-trip "O" timestamps so a DateTimeOffset's offset and ticks survive the
last-writer-wins equality compare, the content type as its enum MEMBER NAME so an
unknown value is rejected rather than decoded to the zero member, and nullable
fields left absent rather than written as "" so null and empty stay distinct.

SecretsHubAuthInterceptor fails closed: with no token configured every call is
denied and one warning names the exact configuration key — never a token value,
presented or configured, at any level. Denial is uniform (one Status, one detail,
no "why") so a caller gets no oracle. Comparison is constant-time over UTF-8
bytes. All four handler shapes are gated, not just unary, so a future RPC cannot
arrive unauthenticated by omission; more than one Authorization header is refused
as a smuggling shape. The type keeps EXACTLY ONE public constructor — Grpc's
activator silently stops invoking an interceptor it cannot construct
unambiguously, and the failure mode is an auth gate that quietly does not run — so
a test pins the count.

Tests: 50, red-first (compile-red, then a fail-closed mutation verified 5 of them
bite). Full Secrets suite 328 passed / 0 failed / 15 live-gated skips, 0 new
warnings.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 06:09:23 -04:00
Joseph Doherty cc95590196 test(secrets): scaffold empty Grpc replicator test project (Tasks 2/3 drop files in without shared-file edits)
Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 05:57:42 -04:00
Joseph Doherty cf6d19d09d docs(secrets): add wire-evolution policy header to secrets_hub.proto (review follow-up)
Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 05:56:09 -04:00
Joseph Doherty 5fd7bf524a feat(secrets): scaffold ZB.MOM.WW.Secrets.Replicator.Grpc + secrets_hub.v1 pull-only proto
Adds the third replicator sibling next to Replicator.SqlServer and
Replicator.AkkaDotNet: the central-hosted gRPC secrets hub. This commit is
scaffold only -- project, wire contract, solution wiring -- no service or
client implementation.

The proto mirrors exactly the read half of ISecretReplicationHub
(GetManifestAsync, GetManyAsync). ApplyReplicatedAsync is deliberately NOT
mirrored: in this topology every update originates at central and a site node
is a strict follower, so the narrow contract IS the enforcement -- with no
write RPC on the wire, a mis-wired or compromised site node has no way to push
a row into the hub regardless of what its authorization allows.

Messages are hand-written mirrors of StoredSecret and SecretManifestEntry
rather than serializations of the domain types, following the Akka
replicator's SecretRowDto precedent: the trust boundary stays structural, and
a field added to StoredSecret later cannot start crossing the network merely
by existing. Timestamps are ISO-8601 "O" strings (not google.protobuf.
Timestamp, which cannot round-trip a DateTimeOffset's offset) so a relayed row
is byte-identical to the one central holds; nullable .NET fields use proto3
explicit presence so null and empty string stay distinguishable.

Grpc 2.76.0 / Google.Protobuf 3.34.1 match what ScadaBridge, OtOpcUa and the
sibling ZB.MOM.WW.LocalDb libraries already resolve, so a consumer taking both
gets one Grpc rather than a downgrade warning.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 05:48:27 -04:00
Joseph Doherty ad7df925ae docs(secrets): gRPC hub implementation plan (9 tasks, subagent-executable) + cached-on-sites posture made explicit
Plan + tasks ledger for scadaproj#3 execution: package (proto/server/client/
tests/publish 0.4.0), ScadaBridge wiring + live gate, OtOpcUa pair-local
re-gate, closeout. GAPS + runbook now state the gRPC mode keeps the
cached-on-site-clusters last-known-good posture (owner-confirmed).

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 05:36:32 -04:00
Joseph Doherty 591307c13e docs(secrets): production replication topologies decided — OtOpcUa Akka pair-local, ScadaBridge central gRPC hub (pull-only); scadaproj#3
Design doc + runbook Production-enablement section + GAPS/index updates.
The previously-untracked production-KEK decision is now recorded: one
fleet-wide KEK via appsettings/env (never committed); ScadaBridge rejects
the SqlServer hub on topology grounds (sites talk to central, never the
DB) in favor of a new ZB.MOM.WW.Secrets.Replicator.Grpc package —
pull-only, updates originate at central only, by design.

Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 05:28:46 -04:00
Joseph Doherty 537a4f524d docs: truth sweep — index + component GAPS reconciled with shipped state (Health 0.3.0 merged both apps, OtOpcUa LocalDb Phase 2 executed, Auth 0.1.5, Secrets 0.2.3/0.3.0)
Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-07 02:00:58 -04:00
Joseph Doherty 1a7bff6a19 docs(index): OtOpcUa #548 FIXED — FOCAS duplicate sibling names disambiguate (AA_1/AA_2, merge 8b5c478c)
Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-06 21:09:30 -04:00
Joseph Doherty c8c4c2bcde docs(index): OtOpcUa #539 FIXED (AbCip browse honours the authored port); #540 CLOSED, axis residual now #548
Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-06 20:48:03 -04:00
Joseph Doherty 35f371ed74 docs(index): OtOpcUa ClusterClient→gRPC program CLOSED — Phase 4 terminal live gate PASS 8/8 (boundary proven, terminal suite 9,333/0)
Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-06 20:30:45 -04:00
Joseph Doherty 63cf4c6f0c docs(index): OtOpcUa Phase 3 ClusterClient deletion MERGED to master @ 2fa880b6; only the Phase 4 terminal gate remains
Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-06 16:58:16 -04:00
Joseph Doherty 0e416cac0a docs(index): OtOpcUa ClusterClient→gRPC migration — Phases 0-2 merged (rig default Grpc), Phase 3 deletion complete on branch pending merge
Claude-Session: https://claude.ai/code/session_014WNM4vjoVksyyBraTXSZE1
2026-08-06 16:24:06 -04:00
Joseph Doherty 7ed2c29842 docs(index): OtOpcUa #541 FIXED — drivers now report the tags they skipped (twelve, not eight) 2026-08-06 02:18:42 -04:00
Joseph Doherty 2b45a59c5d docs(index): OtOpcUa #540 deployed to wonder — the 20 FOCAS fixed-tree tags read 20/20 Good 2026-08-05 18:54:49 -04:00
Joseph Doherty d30f54639f docs(index): FOCAS fixed tree is publishable (OtOpcUa #540); driver Healthy no longer implies tags are polled (#541) 2026-08-05 17:49:11 -04:00
Joseph Doherty 0bbe42eaa1 docs(index): OtOpcUa Sql driver now ships SqlServer + Postgres + Oracle providers 2026-08-05 08:00:14 -04:00
Joseph Doherty 6d222ea491 docs: correct the self-form watchdog record — rejected, not shipped
The InitJoin self-form watchdog (a timer calling Cluster.Join(SelfAddress) after a
window) was implemented and REJECTED after live testing: it sits outside Akka's join
handshake, so on a routine standby restart — peer alive, join stalled behind removal of
the node's own stale incarnation — it fires mid-join, abandons the in-flight join and
forms a permanent second cluster at the same address (measured: still split after 90s;
OtOpcUa hit it live in its manual-failover drill).

The safety argument 'a booting node only self-forms when no seed answers InitJoin' is
true of Akka's NATIVE first-seed rule (FirstSeedNodeProcess, inside the handshake) and
FALSE of the watchdog, which can fire while a seed is answering. That reasoning error is
now called out explicitly so no future plan re-derives the pattern.

- docs/plans/2026-07-22-initjoin-selfform-fallback.md: dated correction banner (history
  preserved) + the two surviving false claims struck in place (behavior-spec row and the
  Mechanism section's 'races are benign'); points at ScadaBridge
  Component-ClusterInfrastructure.md as the surviving design.
- akka_failover.md 6.1: shipped design stated as self-first seed ordering plus the
  opt-in, default-OFF simultaneous-cold-start bootstrap guard; added a
  never-re-derive-the-watchdog note. 6.2: two items my 6.1 edit contradicted are marked
  closed (OtOpcUa auto-down live gate, mesh election scope — both done 2026-07-24).
- CLAUDE.md: ScadaBridge issue #14 is CLOSED (2026-07-24), not open — v3 dual-namespace
  live gates all passed, ScadaBridge consumes OtOpcUa v3 end-to-end.
2026-08-01 11:09:45 -04:00
Joseph Doherty 7a6f997180 docs(index): OtOpcUa #520 complete — ACL grants authored from a scope picker (stage 7)
Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo
2026-08-01 10:54:19 -04:00
Joseph Doherty 555d1b4afc docs(index): OtOpcUa gates reads/browse/subscribe too — the previous entry said the opposite
#520 stage 6 (master 2026-08-01, live-gated). With Security:Acl:Enabled ON,
every data-plane operation needs a matching NodeAcl grant, not just writes /
alarm acks / HistoryRead. The stage-5 entry told ScadaBridge that a read-only
consumer was 'unaffected either way' — that now holds only while the flag is
off, which is the default.

Also records the two stage-6 behaviours a consumer would otherwise discover the
hard way: a deep Browse grant makes its ancestor folders browsable (so it
exposes their names), and revoking a grant stops a live subscription — one
BadUserAccessDenied then silence, resuming by itself if the grant returns, with
no reconnect needed.
2026-08-01 10:00:55 -04:00
Joseph Doherty 883601a72b docs(index): OtOpcUa node ACLs are now enforced behind Security:Acl:Enabled (#520 stage 5)
Default is off, so a read-only address-space consumer is unaffected. With it on,
writes / alarm acks / HistoryRead need a matching grant for the principal the
session authenticates as — anonymous unless ScadaBridge is issued a key.
Reads, browses and subscriptions stay ungated in both modes.

Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo
2026-08-01 05:01:07 -04:00
Joseph Doherty 6b12a7b75e docs(index): OtOpcUa AB CIP/Legacy now honour the authored EtherNet/IP port (#534) 2026-08-01 02:39:06 -04:00
Joseph Doherty 0121f55f1e docs(index): OtOpcUa's OPC UA data plane authenticates with API keys, not LDAP
Gitea #520 (OtOpcUa master, merge fbe7403c) replaced LdapOpcUaUserAuthenticator
with an API-key authenticator on the OPC UA data plane. The index still told a
consumer that enforcement was "LDAP roles plus a write gate", which is now the
wrong instruction for anyone wiring a client.

Records what a consumer actually needs: the UserName/`apikey`/`otua_...` token
shape, that LDAP survives for AdminUI login only, that anonymous still defaults
to admitted (so ScadaBridge is not broken today), and that revocation is
asymmetric because keys reach driver-only nodes inside the deployment artifact.
The "ACLs authored but not enforced" warning stands -- stages 3, 5 and 6 remove
it.

Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo
2026-08-01 00:29:17 -04:00
Joseph Doherty c07659c0e0 docs(index): OtOpcUa #527 fixed — comms-loss is detected and auto-recovers; withdraw the condition-Quality caveat 2026-07-31 10:59:50 -04:00
Joseph Doherty ded7cf0d6d docs(index): OtOpcUa — Sql browser layering (#526), IDriver dead-surface removal (#525), scripted-alarm comms-loss quality (#481) + the #527 caveat 2026-07-31 10:04:50 -04:00
Joseph Doherty f7f4554a36 docs(index): OtOpcUa MQTT driver — write-through (#508), Sparkplug primary-host STATE (#511), structured Template/DataSet flattening (#515)
All three live-gated and merged to OtOpcUa master. The index still said write-through was
deferred and every MQTT node read-only, which #508 changed on 2026-07-31; #511 and #515
landed in merge 857a10b4. Two of the three are consumer-visible to ScadaBridge: MQTT nodes
now materialize Operate rather than ViewOnly where a write destination is declared, and a
Sparkplug UDT surfaces as ordinary scalar nodes instead of being skipped.
2026-07-31 08:15:31 -04:00
Joseph Doherty 850e23646a docs(index): OtOpcUa — #521 host connectivity now consumed via telemetry; #522 tier machinery deleted
Both were recorded as open keep-or-delete decisions; both closed on OtOpcUa master abda6f9e.
Neither changes the OPC UA wire contract, so neither is consumer-facing to ScadaBridge — but
the index asserted them as current state, so it would have drifted.

Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo
2026-07-30 04:59:06 -04:00
Joseph Doherty ff073450dc docs(index): OtOpcUa — tag-set drift detection REMOVED (#523, merge 2a0461a1)
The entry claimed the periodic tag-set drift check had shipped. It was taken back
out two days later and is not in master. Corrected in place rather than deleted,
so the record shows both what landed and what became of it.

Carries forward the consequence a reader needs: AbCip and FOCAS browse a live
backend but implement no IRediscoverable, so they now have no tag-change signal
at all. Galaxy/TwinCAT/MTConnect/Mqtt raise natively and are unaffected. Still
not consumer-facing to ScadaBridge -- no OPC UA wire-contract change either way,
and the IRediscoverable operator prompt is untouched.

Also records the rest of that merge: 13 stale skipped tests retired, a reflection
guard over the deploy-time TagConfig gate, three silently-failing OpcUaClient
integration tests fixed, and the two missing driver guides written.

Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo
2026-07-30 03:42:45 -04:00
Joseph Doherty e96b5d49f9 docs(index): OtOpcUa — deferment remediation merged to master (914d70bf)
The index recorded this as unmerged on a feature branch; it landed on master
2026-07-28. Also records the two follow-ups the first pass had deliberately
left unbuilt and which have since shipped: Sql/FOCAS in-place config re-parse
(made atomic, so a config change cannot half-apply a new tag set against an
old connection or backend), and tag-set drift detection for the four
genuinely-browsable drivers.

Neither is consumer-facing to ScadaBridge — no OPC UA wire-contract change, and
the drift signal is advisory rather than an address-space rebuild. The
previously-noted operationally-visible item stands: a DriverConfig edit now
costs a driver reconnect.
2026-07-28 13:24:36 -04:00
Joseph Doherty b0b57f8d54 docs(index): OtOpcUa — rediscovery is now a prompt; deferment remediation underway
Corrects a fact this index recorded two days ago as consumer-relevant to
ScadaBridge. "IRediscoverable is inert fleet-wide" no longer holds: it is
consumed as an operator re-browse prompt on /hosts, carried on
DriverHealthChanged. The consumer-facing conclusion is unchanged and worth
keeping explicit — the served address space still only changes on a config
redeploy, because the prompt is advisory by design.

Gitea #507 (discovered-node injection) is closed as superseded and its code
deleted; it read two structures that are structurally empty in v3, so it could
never have injected anything. #521 tracks the still-unconsumed
IHostConnectivityProbe.

Adds the remediation status for the deferment register (branch
feat/deferment-remediation, tip 88ce8df0, unmerged). One item there is
operationally visible beyond OtOpcUa: #516 makes a changed DriverConfig
stop+respawn the driver rather than an in-place delta, so a config edit now
costs a driver reconnect — previously five drivers ignored the edit entirely
while the deployment still sealed green.
2026-07-27 20:04:32 -04:00
Joseph Doherty eedbf13712 docs(index): OtOpcUa — mesh program COMPLETE (Phase 7 + bootstrap guard), deferment register
Corrects four stale claims about OtOpcUa and adds two consumer-relevant facts,
all source-verified against the OtOpcUa repo (not its docs):

  * "Phases 0a..6 done, 7 not started" -> PROGRAM COMPLETE. Phase 7 merged
    c50ebcf7 (6/6 failover drills) + bootstrap guard d1dac87f, both on master
    and pushed 2026-07-24.
  * The auto-down 1-vs-1 crash-the-oldest live gate is no longer "still open" /
    "deferred to Phase 7" — Phase 7 drill D4 closed it; every survivor stayed
    Up without self-downing.
  * Phase 6's live gate was NOT "deferred by owner choice" — it ran and caught
    three fix-forward defects, including a boot-crash StackOverflow on every
    node (IClusterRoleInfo resolved inside the AddAkka configurator while the
    ActorSystem was still building).
  * Records the MAIN-only manual-failover constraint and the default-OFF
    bootstrap guard's founder-election shape.

Adds OtOpcUa/deferment.md (e08855fb) and its two ScadaBridge-relevant entries:
  * Node ACLs are authored, shipped in every artifact, and NOT ENFORCED — the
    evaluator subsystem has zero production consumers and OtOpcUaNodeManager
    never references it. Reads are ungated; authored deny rules have no effect.
    Do not assume OtOpcUa filters an address space per-user.
  * IRediscoverable is inert fleet-wide (#518/#507) — nine drivers raise it,
    nothing consumes it, so a Galaxy redeploy / PLC re-download / Agent restart
    does not change the served address space without a config redeploy.
2026-07-27 17:28:28 -04:00
Joseph Doherty 035c5feeb8 Merge branch 'feat/overview-dashboard'
# Conflicts:
#	CLAUDE.md
2026-07-27 15:26:37 -04:00
Joseph Doherty b02d7a92bb docs(index): record OtOpcUa's MTConnect Agent driver (merged to master, PR #506)
Keeps the umbrella index in step with the OtOpcUa driver set, per the
propagation rule in that repo's CLAUDE.md. Read-only Agent driver:
hand-rolled HTTP/XML client (probe/current + multipart /sample pump),
TrakHound dependency evaluated and dropped, browse free via the Wave-0
universal discovery browser, write-back deferred. Live-gated against a
real mtconnect/agent 2.7.0.12 fixture.
2026-07-27 14:03:15 -04:00
Joseph Doherty 75f267c4c9 docs(index): index edits go on main and get pushed
Sister projects are told to update their entry here whenever an indexed fact
changes, but that edit lands in this repo's own checkout — so a naive commit
writes it onto whatever branch scadaproj happens to be on. Observed 2026-07-27:
the OtOpcUa Sql driver's entry sat unpushed on feat/overview-dashboard for three
days, and the Mqtt entry was about to join it.

Records the procedure (stash, main, push, restore) and says to cherry-pick
stranded index commits rather than merge the branch they are stuck on.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-27 13:36:18 -04:00
Joseph Doherty 7dcd93c326 docs(index): OtOpcUa's MQTT / Sparkplug B driver is merged to master
Merge c3a2b0f7, pushed to origin 2026-07-27. Supersedes the
"on branch feat/mqtt-sparkplug-driver, not yet merged" note in bf75e26.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-27 13:34:10 -04:00
Joseph Doherty 591eaac881 docs(index): record OtOpcUa's MQTT / Sparkplug B driver
The OtOpcUa entry's driver set changed, so the index has to change with it
(OtOpcUa CLAUDE.md's cross-repo rule).

A read-only `Mqtt` broker-subscribe driver landed with two ingest shapes over
one MQTTnet-5 client: Plain binds a tag to a concrete topic, SparkplugB decodes
vendored Eclipse-Tahu protobuf under a single spBv1.0/{groupId}/# subscription
and binds by the group/edgeNode/device?/metric tuple (birth/alias/seq-gap/
rebirth state machine, death→STALE, a birth-driven browse picker with a scoped
Request-rebirth NCMD). Write-through is deferred — every MQTT node is read-only.

Live-gated on docker-dev against a Mosquitto TLS+auth broker plus a
project-owned C# Sparkplug edge-node simulator on 10.100.0.35:8883.

Recorded as **on branch feat/mqtt-sparkplug-driver, not yet merged to master**,
so the index does not overstate what is on OtOpcUa's default branch — unlike the
Sql DB-poll driver next to it, which is merged.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-27 13:34:10 -04:00
Joseph Doherty 6ab50fed1f docs(index): add the OtOpcUa Sql poll driver to the driver set
OtOpcUa merged a read-only Sql Equipment-kind driver to master 2026-07-24
(polls SQL Server → OPC UA variables; connectionStringRef env resolution,
schema-walk address picker, live /run gate passed on docker-dev). Keep the
umbrella index's OtOpcUa driver enumeration in sync per the propagation rule.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-27 13:34:10 -04:00
Joseph Doherty a58d79b793 docs(index): OtOpcUa's MQTT / Sparkplug B driver is merged to master
Merge c3a2b0f7, pushed to origin 2026-07-27. Supersedes the
"on branch feat/mqtt-sparkplug-driver, not yet merged" note in bf75e26.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-27 13:33:28 -04:00
Joseph Doherty bf75e265ab docs(index): record OtOpcUa's MQTT / Sparkplug B driver
The OtOpcUa entry's driver set changed, so the index has to change with it
(OtOpcUa CLAUDE.md's cross-repo rule).

A read-only `Mqtt` broker-subscribe driver landed with two ingest shapes over
one MQTTnet-5 client: Plain binds a tag to a concrete topic, SparkplugB decodes
vendored Eclipse-Tahu protobuf under a single spBv1.0/{groupId}/# subscription
and binds by the group/edgeNode/device?/metric tuple (birth/alias/seq-gap/
rebirth state machine, death→STALE, a birth-driven browse picker with a scoped
Request-rebirth NCMD). Write-through is deferred — every MQTT node is read-only.

Live-gated on docker-dev against a Mosquitto TLS+auth broker plus a
project-owned C# Sparkplug edge-node simulator on 10.100.0.35:8883.

Recorded as **on branch feat/mqtt-sparkplug-driver, not yet merged to master**,
so the index does not overstate what is on OtOpcUa's default branch — unlike the
Sql DB-poll driver next to it, which is merged.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-25 01:12:09 -04:00
Joseph Doherty 8698d1804b docs(index): add the OtOpcUa Sql poll driver to the driver set
OtOpcUa merged a read-only Sql Equipment-kind driver to master 2026-07-24
(polls SQL Server → OPC UA variables; connectionStringRef env resolution,
schema-walk address picker, live /run gate passed on docker-dev). Keep the
umbrella index's OtOpcUa driver enumeration in sync per the propagation rule.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-24 21:02:44 -04:00
Joseph Doherty 344bdc4da5 fix(overview): rank activeNode over leader for the Active chip
The dashboard derived every leader chip from AkkaClusterHealthCheck's `leader`
data — ClusterState.Leader, the LOWEST-ADDRESSED Up member. That is not the node
in charge. The node holding the singletons, gated for writes, and answering 200
on /health/active is the OLDEST Up member. The two agree only until some node
restarts, after which the restarted node rejoins youngest but keeps its address.

Observed live on the rebuilt OtOpcUa rig during the Health 0.3.0 work: leader
central-1, active node central-2. The dashboard would have put the Active chip on
central-1 while /health/active said central-2 — the chip contradicting the tier
it exists to visualise. The Phase 4 acceptance run missed it because the rig had
just been formed, the one state in which the two orderings agree.

Health 0.3.0's active tier now publishes `activeNode` on every member, including
standbys, so the fix is to prefer it and keep `leader` as the fallback for an
instance on an older Health or whose active tier was not probed.

The instance card now shows `active` and `leader` side by side rather than
swapping one for the other: they are legitimately different nodes, and showing
both turns a silent contradiction into something readable at 3am.

Tests: 177 (+3) — precedence when the two disagree, a standby naming the active
node rather than itself, and the fallback still working with no activeNode.
2026-07-24 13:27:07 -04:00
Joseph Doherty 6a4fa220de docs(health): oldest-Up-member is the active-node rule (0.3.0)
Rewrites the active-node sections of the spec and shared contract, which
described the leader-based design that both consumers rejected.

- SPEC §2.3 replaced: the rule, the ordered RolePreference, why a node holding
  none of the preferred roles is Unhealthy rather than Healthy, and the data
  payload. §4 (IActiveNodeGate) and the tier table follow.
- SPEC §6 marked historical: it still tells adopters to use
  ActiveNodeHealthCheck(role: "admin") and AkkaActiveNodeGate, which is the
  advice that produced the defect. Kept for provenance, annotated so nobody
  follows it again.
- GAPS: gaps L1/L2 recorded as closed the wrong way, reopened, then closed at
  0.3.0 — including the part worth remembering, that both apps adopted the
  shared check as specified, hit it live, and reverted to private copies, so the
  surface reached zero consumers by being avoided rather than unused.
- Index rows updated with the consumer-visible changes and both app branches.
2026-07-24 13:24:30 -04:00
Joseph Doherty a61e041e58 feat(health)!: active node is the oldest Up member, not the leader (0.3.0)
Promotes the two apps' private replacements for ActiveNodeHealthCheck into one
shared primitive, and retires the leader/RoleLeader selection they were written
to avoid.

Both Akka consumers had already hand-rolled a replacement rather than use this
package (ScadaBridge OldestNodeActiveHealthCheck, OtOpcUa
ClusterPrimaryHealthCheck), so the entire active-node surface here —
ActiveNodeHealthCheck, AkkaActiveNodeGate — had ZERO consumers. It was not
merely unused: it was avoided, twice, for the same reason.

Leadership is address-ordered (host, then port) and has no relationship to time;
singleton placement is age-ordered. The two agree on a freshly-formed cluster,
which is why single-node and happy-path tests never caught it. They diverge
permanently after any restart: the restarted node rejoins as the youngest but
keeps its address, so if it holds the lower address it becomes leader while the
singletons — and all the work they own — stay on the other node.

New ClusterActiveNode is the single implementation: oldest Up member, optional
role scope, plus role-preference resolution for a fused node that must answer
for the role its singletons are pinned to. ActiveNodeHealthCheck and
AkkaActiveNodeGate both delegate to it, so an endpoint gate and the
/health/active probe an orchestrator routes by cannot disagree.

BREAKING (behaviour, not signature):
- Selection is by age, not leadership.
- The role-filtered mode no longer reports Healthy for a node LACKING the role.
  That "not applicable => Healthy" made the tier answer 200 on every node and
  silently broke leader-pinning (lmxopcua#494); it is now Unhealthy by default,
  overridable via NoActiveRoleStatus. This case is reachable, not defensive —
  OtOpcUa's RoleParser admits dev-only and cluster-role-only nodes.
- Identity compares UniqueAddress, so a node restarted on the same host:port is
  correctly a different member during the overlap.

Results now carry activeRole/selfAddress/activeNode in the 0.2.0 per-entry data
object, so a standby reports WHO is active and a dashboard can render a pair
from either node's payload alone.

Tests: 45 Akka (was 39), 76 total. The age-vs-address divergence is pinned
against a real two-node cluster built so the oldest member is not the
lowest-addressed one, with a fixture sanity check so it cannot pass for the
wrong reason.
2026-07-24 13:07:56 -04:00
Joseph Doherty c81a6615ba docs(overview): Phase 4 check 1 now passes for both products (lmxopcua#494 closed) 2026-07-24 12:46:05 -04:00
Joseph Doherty 280e57896b docs: Health 0.2.1 active-tier fix — index row + Phase 4 ledger 2026-07-24 11:31:31 -04:00
Joseph Doherty af1e0a86b2 fix(health): active tier returns 503 on a role-member-but-not-leader node (0.2.1)
The shared spec states the active tier "Fails (503) on a standby or
role-member-but-not-leader node", and the same spec maps Degraded to HTTP 200.
ActiveNodeDecision.Evaluate returned Degraded for exactly that case, so the tier
answered 200 on every node and could not distinguish an active node from a
standby over HTTP at all - only the response body differed.

The consequence was live, not theoretical: OtOpcUa's Traefik routes the admin UI
by this probe (docker-dev/traefik-dynamic.yml, scripts/install/traefik-dynamic.yml),
so both central nodes always passed and the leader-pinning the design called for
has silently never worked. Found while running the overview dashboard's live
acceptance, which reads the same tier and showed all six rig nodes as Active.
Filed as lmxopcua#494.

Role-member-but-not-leader now returns Unhealthy. The other two branches are
unchanged: a node that lacks the role stays Healthy (the probe is irrelevant to
it), and the startup-safety path still returns Degraded when the ActorSystem or
cluster is not yet available.

Blast radius is one consumer. OtOpcUa is the only user of the role-filtered mode;
ScadaBridge deliberately uses its own OldestNodeActiveHealthCheck (leadership is
address-ordered and diverges from the singleton host), and MxGateway and
HistorianGateway have no Akka cluster.

Version 0.2.1, three packages published to the Gitea feed and restore-verified.
70 tests pass.
2026-07-24 10:46:04 -04:00
Joseph Doherty c22b06deba docs(overview): link the OtOpcUa active-tier finding to lmxopcua#494 2026-07-24 10:40:45 -04:00
Joseph Doherty d95292c95d fix(overview): locate the cluster view by data key, not by check name
Found by the live rig, and invisible to every unit test that existed.

LeaderResolver and InstanceCard.ClusterDataLine both looked the cluster view up
under the check name "akka-cluster". ScadaBridge registers the shared
AkkaClusterHealthCheck under that name; OtOpcUa registers the SAME check as
"akka". So once the OtOpcUa rig was rebuilt on Health 0.2.0 and started
publishing data.leader, its groups still rendered with no leader chip and no
evidence line - and a group with no votes is a legitimate state, so nothing
looked wrong. ScadaBridge's four groups were fully populated the whole time,
which is what made it look like the feature worked.

Both now find the entry by the DATA KEY ("leader"), which is the part of the
contract the shared check actually owns rather than the part each consumer names
for itself.

Regression tests: the leader is found under akka-cluster, akka, and an arbitrary
future name; and an entry that publishes data WITHOUT a leader (ScadaBridge's
localdb check, whose data carries replication counters) does not get picked in
preference to the one that answers the question. Every prior fixture used
ScadaBridge's name, which is precisely why this got through.

After the fix all seven cluster groups render a leader chip with zero
split-brain flags - design section 9 check 2 now passes for BOTH products.

174 tests, 0 warnings.
2026-07-24 10:38:39 -04:00
Joseph Doherty 41013dcab3 fix(overview): call UseStaticWebAssets unconditionally; record Phase 4 results
Found during the live acceptance run. The host calls UseStaticWebAssets only when
the environment is literally "Development", so running the build output under any
other name - checking a staging registry locally, say - leaves the Theme RCL's
assets under _content/ unresolvable. The failure is silent and unhelpful: the page
returns 200 with its markup fully present and renders as a blank white screen,
because every stylesheet 404s. Calling it unconditionally is a no-op once
published (the manifest is gone and the assets are real files on disk), so the
only thing it changes is that failure. The container was never affected.

Phase 4 results recorded in the ledger: 7 of 9 design section 9 checks fully pass,
2 pass for ScadaBridge and are blocked for OtOpcUa pending a rig redeploy.

Notable live evidence:
- Leader chip moved from site-c-a to site-c-b when site-c-a was stopped, and the
  split-brain chip appeared while the pair was self-formed then cleared once it
  genuinely joined.
- Kill to Unreachable took two failing sweeps (the damping working as designed);
  recovery landed on the first good poll.
- Five consecutive page loads in 0.00-0.02s all showed the same "last sweep"
  timestamp, which is cache-first stated as a measurement.
- Freezing the probed endpoints while auto-refresh stayed RUNNING froze the poller
  mid-sweep and the cards aged into STALE on their own - staleness is computed at
  render, so a stuck poller needs no explicit stall detection.

The run also surfaced a pre-existing rig defect in both products: self-first Akka
seed lists mean a pair booted cold self-forms two 1-member clusters that never
join. After a --force-recreate every ScadaBridge node named ITSELF leader and every
node answered /health/active 200; restarting ONE node of each pair converged them
to one Leader plus one Active plus one Standby. That is the user's own open backlog
item (docs/plans/2026-07-22-initjoin-selfform-fallback.md, unexecuted), and the
dashboard made it visible fleet-wide in one screen.

170 tests, 0 warnings.
2026-07-24 08:19:41 -04:00
Joseph Doherty 92997b40dc feat(overview): self-observability, config and the container image
Closes Phase 3 of the overview-dashboard plan (tasks 3.7-3.9).

Self-observability
- OverviewMetrics: an observable gauge read from the published snapshot at scrape
  time, so the metric and the page cannot disagree about what the dashboard
  believes, plus a sweep-duration histogram. Instrument names follow the family
  METRIC-CONVENTIONS spec (overview.instance.status / overview.poll.duration,
  unit s) rather than the plan's literal zb_ names; Prometheus renders them as
  overview_instance_status and overview_poll_duration_seconds. Labels are
  application/node/group - "node", not "instance", because Prometheus stamps its
  own instance label on every scraped series and a colliding metric label is
  silently renamed exported_instance. Instances never probed emit nothing: the
  enum's zero ordinal is Up, so a placeholder would publish the single most
  reassuring answer about a node nobody has heard from.
- Two readiness checks make the dashboard's own /health/ready mean something:
  registry-loaded (reports the counts it bound) and last-poll-cycle-completed,
  which catches the failure where Kestrel is fine, the page still renders, and
  every card on it is quietly frozen. The heartbeat is stamped by the sweep, not
  derived from the snapshot's timestamp - the poller publishes the registry
  before it probes anything, so a stuck poller would otherwise look healthy.
  No cycle yet is Degraded inside the grace window and Unhealthy past it, so a
  restart does not fail readiness for its first seconds and a poller that never
  started cannot hide behind "still starting".

Configuration
- appsettings.json ships tuning defaults with an EMPTY Applications list, so a
  deployment that supplies no registry fails at ConfigPreflight naming the key
  instead of booting into a dashboard of nothing.
- Three registries, because reachability genuinely differs: Development is the
  host-reachable subset (4 instances), Docker is the full 16-instance fleet by
  container DNS name. The rigs publish almost no per-node HTTP port to the host
  - OtOpcUa publishes none (only Traefik :9200, load-balanced across the central
  pair, so it cannot identify a node) and ScadaBridge keeps site :8084
  container-internal. Ports were established by probing the running rigs, not
  read off the compose files, because the two disagree: OtOpcUa site nodes serve
  health on :8080, not the :9000 their compose anchor implies.
- Real Serilog sinks, not the family's empty "Serilog": {}. AddZbSerilog drives
  sinks entirely from configuration and adds none of its own, so the empty
  section produces an app that logs NOWHERE - verified against the running
  HistorianGateway container, whose log stream is completely empty for exactly
  this reason. The HttpClient level override matters too: 16 instances on a 10s
  cadence emit several Information lines a second of pure probe noise.

Container
- HistorianGateway-pattern runtime-only image; the compose stack joins the three
  rig networks as external, so bringing the dashboard up or down cannot disturb
  a rig. The Dockerfile clears ASPNETCORE_HTTP_PORTS as well as ASPNETCORE_URLS:
  on .NET 8+ the base image declares its binding via the former, and clearing
  only the latter leaves Kestrel logging "Overriding address(es)" every boot.
  No healthcheck - aspnet:10.0 has neither curl nor wget, and adding a
  --healthcheck entry point to production code to satisfy Compose is not a
  trade worth making.

Tests
- BootTests boot the real Program.cs: every endpoint anonymous, the page
  rendering from cache while nothing it watches is reachable, the Meters
  allowlist proven by an end-to-end /metrics scrape, and both refuse-to-boot
  paths (missing registry, stale window inside the poll interval).
  The registry is supplied via environment variables, not
  ConfigureAppConfiguration, because ConfigPreflight runs before Build() - when
  the factory's callbacks are applied - and would not see them.

170 tests, 0 warnings. Verified live against the running rigs: 16 cards, 16
gauge series, page and gauge agreeing exactly.
2026-07-24 07:35:32 -04:00
Joseph Doherty 5fe7135e2c feat(overview): poller, leader aggregation and the dashboard UI
Tasks 3.4-3.6 of the overview-dashboard plan.

Polling (3.4/3.5):
- OverviewPollerService: one timer at the fastest configured cadence, each
  target polled when its own interval is due, fan-out per sweep, no retries
  (the next tick is the retry, so damping stays the only place that decides
  whether a failure is worth showing).
- OverviewSnapshotStore: atomic swap of a complete immutable graph plus a
  change event. Pages read it and never probe — the cache-first requirement.
- LeaderResolver: per-group leader from akka-cluster data, with the
  split-brain flag scoped to members that are actually answering, so an
  ordinary failover is not misread as a disagreement.

UI (3.6): ThemeShell + StatusPill/TechCard composition against the mockup;
instance cards carry the status stripe (dashed for Unreachable), the check
detail list and the raw ready/active signal line.

Two defects found by verification rather than by review:

- The active tier answers with a status code and an EMPTY body, but the client
  demanded parseable JSON on every probe — so a healthy pair rendered as
  "role unknown" instead of Active/Standby. Split into ProbeAsync (ready tier,
  body is the payload) and ProbeStatusAsync (active tier, code is the answer).
  Caught by a live smoke run against two fake health endpoints; the poller
  tests now serve an empty body so they hold the fix.

- SweepAsync published even when cancellation was already requested, leaving a
  half-probed registry as the store's final state on shutdown. It now checks
  the token itself rather than relying on the transport to throw.

Also: app.UseAntiforgery() is required despite the anonymous-by-design
pipeline — AddRazorComponents stamps antiforgery metadata unconditionally and
the endpoint middleware hard-fails without it (every page was 500). Chosen
over DisableAntiforgery() so a future form is protected by default.

147 tests, 0 warnings. Live-verified end to end against fake endpoints:
Up/Unreachable/Active/Standby, leader chip, cluster-data line, KPI counts.
2026-07-24 07:05:16 -04:00
Joseph Doherty 61fc88c8a8 chore(plan): overview dashboard task ledger through task 3.3 2026-07-24 06:42:28 -04:00
Joseph Doherty d0110cf406 feat(overview): scaffold the family dashboard + registry + health client
Phase 3 tasks 3.1-3.3 of docs/plans/2026-07-22-overview-dashboard-impl-plan.md.

Scaffold (3.1): a plain directory in scadaproj (NOT a nested git repo), slnx over
src/ + tests/, HistorianGateway-pattern Directory.Build.props (warnings-as-errors)
and nuget.config (nuget.org * + the Gitea feed scoped to ZB.MOM.WW.*). Inline
package pins, no CPM — the app convention here. NO Auth/Audit/Secrets packages:
the dashboard is anonymous and read-only by requirement.

Registry (3.2): OverviewOptions/ApplicationEntry/InstanceEntry bound from the
"Overview" section, plus EffectiveTimings resolving instance > application >
global overrides in ONE place so no caller re-implements the precedence.
OverviewOptionsValidator (OptionsValidatorBase + AddValidatedOptions) rejects an
empty registry, applications with no instances, duplicate names, non-absolute or
non-http(s) URLs, and non-positive intervals — and checks stale > poll on the
EFFECTIVE values, since an override at either level can invert that on one
instance while the globals look fine. A ConfigPreflight presence check runs before
the host is built so a missing registry fails with the key name, not with
"Applications must have at least 1 entry".

Health client (3.3): ZbHealthReport DTOs for the canonical ZbHealthWriter body,
with per-entry `data` kept as JsonElement — it is an open contract, and binding it
to concrete types would break the moment a check adds a field. 200 AND 503 are
both parseable answers (503 carries the body naming the failing check); only a
transport failure or a non-canonical body is a failed probe, which is why
Unreachable stays distinct from Down. Host shutdown propagates as cancellation
rather than being recorded as every instance timing out.

Status model: Up/Degraded/Down/Unreachable + Active/Standby/Unknown/NotApplicable,
with two-strike flap damping — a failing observation only replaces a good state
after 2 consecutive failures, while recovery is immediate (damping suppresses
false alarms; symmetric damping would just make them linger).

53 tests green, 0 warnings in Debug and Release. Tests for the validator, the
client golden payloads (with AND without `data`, so a partly-bumped fleet renders)
and the derivation table are front-loaded here from task 3.8 so this batch is
verified rather than pending.

Also pins AngleSharp 1.5.2 test-side: bunit 1.40.0 pulls 1.2.0, which trips NU1902
and therefore the warnings-as-errors gate (same fix HistorianGateway made in
6bc005d).
2026-07-24 06:42:21 -04:00
Joseph Doherty 80668a07bd feat(health): 0.2.0 — optional per-entry data + Akka cluster-view
Phase 0 of docs/plans/2026-07-22-overview-dashboard-impl-plan.md: give the
canonical health JSON a structured channel so the family overview dashboard can
read each Akka cluster's current leader.

- ZbHealthWriter: optional `"data": {...}` per entry, sourced from
  HealthReportEntry.Data, emitted only when non-empty. Per-property JsonIgnore
  (NOT a global DefaultIgnoreCondition) so `"description": null` still renders —
  payloads from data-less checks stay byte-identical to 0.1.0.
- AkkaClusterHealthCheck: BuildClusterData publishes this node's own view —
  leader (omitted while unknown), selfAddress, selfRoles (sorted), memberCount,
  unreachableCount — on every result path. The startup-safety paths (no
  ActorSystem / cluster inaccessible) stay description-only.
- Tests: writer data emit/omit (raw-JSON assert on the omit case), and a real
  single-node self-joined cluster via Akka.TestKit.Xunit2 for the data values.
  70 tests green (25/39/6).
- Version 0.1.0 -> 0.2.0; 3 packages published to the Gitea feed and
  restore-verified from a scratch consumer, which serves data.leader live.
2026-07-24 05:38:36 -04:00
Joseph Doherty 6721c8a224 docs(index): OtOpcUa Phase 6 (mesh partition) done+merged — per-cluster meshes, per-Cluster Primaries
Per-cluster mesh Phase 6 merged to OtOpcUa master 2839deb5 (pushed 2026-07-24).
Records the split into one 2-node mesh per application Cluster, the consumer-visible
per-Cluster ServiceLevel/Primary scoping (two+ Primaries fleet-wide by design, no
wire-contract change), the SplitTopologyTransportValidator, pair-local secrets, and
the deferred live gate.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-24 04:40:23 -04:00
Joseph Doherty 3dbd6cd57c docs(index): OtOpcUa per-cluster mesh Phase 5 done (gRPC telemetry stream, merge 35552a96)
Phases 0a/0b/1/2/3/4/5 done; tip 35552a96. Phase 5 = gRPC live-telemetry stream
behind Telemetry:Mode/TelemetryDial:Mode dark switch; not consumer-facing (central<->node
observability, no OPC UA wire-contract change).

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-23 17:22:18 -04:00
Joseph Doherty 92015da4e0 docs: ScadaBridge OtOpcUa v3 nsu= cutover phase 2 shipped, A/B/C deferred (ScadaBridge #14) 2026-07-23 15:23:35 -04:00
Joseph Doherty 1911de2c3c docs(index): OtOpcUa per-cluster mesh Phase 4 done (cut driver ConfigDb)
Phase 4 merged + pushed (tip 3a590a0c): driver-only nodes run with no ConfigDb
connection string. Consumer-visible ServiceLevel change — a DB-less site node
now holds 240/250 with central SQL down (survive-alone), where a DB-backed node
would drop to 0/100. Phases 0a/0b/1/2/3/4 done; 5-7 not started.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-23 14:35:30 -04:00
Joseph Doherty b5e7bc8b3c docs(index): OtOpcUa per-cluster mesh Phases 1/2/3 done (config fetch-and-cache)
Update the OtOpcUa entry: the per-cluster mesh election-scoping fix now has Phases
0a/0b/1/2/3 merged + pushed (tip d01b0695). Phase 2 = ClusterClient command transport
(MeshTransport:Mode dark switch). Phase 3 = config fetch-and-cache — a FetchAndCache
driver node boots + serves last-known-good with central SQL down (extends the #485
availability guarantee consumers like ScadaBridge rely on); a failed fetch is 'no answer',
never an empty config. Live gate caught + fixed a Status==Sealed serve-gate deadlock.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-23 11:09:17 -04:00
Joseph Doherty 4d93d2580b docs(akka): ClusterClient→gRPC migration design + chunking addendum
akka_msquic_transport.md gains §8a (Akka.Cluster.Chunking / Akka.Delivery —
the 1.5-era in-cluster large-message tool, why it can't cross the ClusterClient
boundary) and the Artery-now-in-development §9 fix.
scadabridge_clusterclient_to_grpc.md: full migration assessment — ClusterClient
inventory (two-actor choke points, 29 commands incl. one dead), gRPC-only
design (topology, oneof contracts, active-node analysis: singleton-routed so
transport needs only either-node failover+failback), PSK-from-Secrets auth,
frame-cap-raise tradeoffs, and §7 deep-dive corrections. Companion impl plan
lives in ScadaBridge/docs/plans.
2026-07-22 17:10:30 -04:00
Joseph Doherty 6dd7858619 docs(overview): family overview dashboard — options, design, impl plan, mockup
Options investigation (Aspire standalone/HealthChecks.UI/Gatus/Homepage/
Grafana vs custom) → decision: custom ZB.MOM.WW.Overview Blazor app in the
family look. Design: anonymous read-only single pane, appsettings registry
of all four apps' instances, cache-first poller on a configurable timer,
configurable staleness timeout, Active/Standby from /health/active, and
per-cluster Akka leader chips (needs Health 0.2.0 optional per-entry data).
Impl plan: phased + code-verified — Phase 0 Health 0.2.0 (writer data field
+ AkkaClusterHealthCheck cluster view), Phase 1 ScadaBridge site-node
MapZbHealth PR (:8084; role-scoped active check), Phase 2 OtOpcUa bump,
Phase 3 the app (:5320), Phase 4 live rig acceptance. Mockup is the visual
reference: real Theme tokens + embedded IBM Plex, all card states incl.
stale + split-brain. Ready to execute in a fresh session.
2026-07-22 09:22:13 -04:00
Joseph Doherty ff58ad4f60 docs(akka-msquic): 1.6 status update — Artery-TCP implementation began 2026-07-03
Corrects the same-day report: PR searches for 'quic' missed work named
'artery'. Artery is landing rapidly on upstream dev as Artery-TCP (openspec
#8313; framing/handshake G1-G2; parallel lanes #8356/#8357; large-message
streamId 3 #8352; MNTR/CI for both transports), with Serialization.V2 in
parallel. TCP-first resolves §7's forward note: pipeline benefits arrive
without libmsquic, dropping the §6 platform constraints from the 1.6
adoption path. No previews or public benchmarks yet.
2026-07-22 06:49:39 -04:00
Joseph Doherty dbfd5e7a7e docs: Akka.NET transport deep-dives — MsQuic/1.6 Artery and multi-DC clusters
Two research reports (2026-07-22):
- akka_msquic_transport.md: what a QUIC transport on Akka 1.5.62 would take,
  the 1.5-vs-1.6 pipeline delta that gates the benefits, .NET-native
  alternatives (managed sockets ranked first), and measured throughput
  evidence (PR #4594: transport swap is throughput-neutral).
- akka_multidc_clusters.md: JVM multi-DC semantics mapped onto the
  central-pair + site-pairs topology, the stalled Akka.NET port (#3261 /
  PR #4111), per-system fit vs the OtOpcUa mesh program, and the
  before-Phase-2 decision point.
Recommendation in both: don't build; track upstream.
2026-07-22 06:41:36 -04:00
Joseph Doherty 5919e29969 docs(index): record OtOpcUa's two redundancy corrections and the NU1903 pin
Both are consumer-visible, so they belong in the index rather than only in the
repo. The downing strategy moved to AutoDowning because a two-node OtOpcUa pair
on keep-oldest could not survive a crash of the oldest node — the same defect and
the same fix as ScadaBridge cf3bd52f, which is where the analysis came from. And
the redundancy Primary is now the oldest Up driver member rather than the role
leader, which changes which node advertises ServiceLevel 250 after a restart —
relevant to anything selecting a server by ServiceLevel.

Also notes that the four NU1903 advisories which broke ScadaBridge's fresh
restores were breaking OtOpcUa's too, and that the election remains scoped per
Akka cluster until the per-cluster mesh work lands.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-21 19:05:27 -04:00
Joseph Doherty ede5275d3a docs(index): OtOpcUa address-space availability guarantee; track the OtOpcUa LocalDb design
The #485/#486 fixes changed nothing structural about OtOpcUa — same drivers,
same dual-namespace scheme, same Galaxy flow — so the row is mostly untouched.
What DID change is a fact any OPC UA consumer depends on, and ScadaBridge is
mid-cutover onto exactly this address space: a transient ConfigDb error used to
empty the served address space (a PureRemove of every node, observed live and it
stayed empty), stop every driver and clear every subscription, while still
reporting the deploy Applied. A consumer would have seen all bindings go bad
with nothing upstream admitting a problem. Recorded on the OtOpcUa row.

Also fixes real drift found while checking: the OtOpcUa LocalDb adoption design
was sitting UNTRACKED here and unreferenced by the index, even though the
LocalDb row claims the adoption designs live in this repo. Now committed,
referenced alongside the ScadaBridge one, and its stale header corrected —
it still said Phase 1 was "not yet executed" against lib 0.1.1, when Phase 1
shipped and merged against 0.1.3. Phase 2 designed but not executed, on both
the doc and the row.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-21 03:30:36 -04:00
Joseph Doherty 4f33eccfa7 Merge fix/localdb-wiped-peer-snapshot: LocalDb 0.1.3 rebuilt-peer replication fixes
Two defects about a node whose LocalDb file is lost, the second only reachable
once the first was fixed:

- 0.1.2 — a converged pair prunes its oplog to empty on ack, and snapshot
  detection read an empty oplog as 'no gap possible'. The steady state of a
  healthy pair was the one state from which a rebuilt node could never be
  back-filled.
- 0.1.3 — with back-fill working, the rebuilt node's OWN writes were silently
  dropped: last_applied_remote_seq is a watermark in the peer's seq space and a
  rebuilt peer numbers from 1, so the healthy node's stale watermark made the
  sending side skip its whole oplog.

Both found by the OtOpcUa LocalDb Phase 1 live gate on the docker-dev rig and
reproduced offline as RED tests first. 149/149 pass.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-21 02:17:42 -04:00
Joseph Doherty 7c8dd654ba docs(index): LocalDb 0.1.3 — the rebuilt-peer write-drop fix
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-21 02:13:48 -04:00
Joseph Doherty 3b7489a7b0 fix(localdb): a rebuilt peer's own writes were silently dropped
The other half of the rebuilt-peer story, and only reachable once 0.1.2 made
back-fill work: with the wiped node repopulated and writing again, its writes
never reached its peer.

last_applied_remote_seq is a watermark in the PEER's seq space, and a rebuilt
peer is a new database whose oplog numbers from 1. Two things then went wrong,
and both had to be fixed — the first alone leaves data stuck:

- The healthy node kept advertising the OLD peer's watermark, and the sending
  side seeds its pump from exactly that number, so the rebuilt node skipped its
  entire oplog. The watermark (and the observed peer clock) is now reset when
  the peer's node id changes. last_acked_seq is deliberately NOT reset: it
  describes our own oplog's pruned horizon and is what tells a rebuilt peer it
  needs a snapshot — clearing it would turn 0.1.2's back-fill back off.

- A peer claiming to have applied more of our stream than we have ever produced
  can only be remembering a previous incarnation of us. That claim is now
  rejected in favour of starting from the beginning; LWW makes the re-send
  harmless. This mirrors the clamp RecordPeerAckAsync already applies to acks.

Found on the OtOpcUa docker-dev rig, where the healthy node held watermark 10
while the rebuilt peer's oplog was seqs 1-3 and its last_acked stayed 0 — the
peer never accepted a single one. Covered by a test that converges with one
peer, replaces it with a fresh database, and requires a write on the new peer
to arrive: RED before this fix, green after. 149/149 pass.

Version 0.1.3.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-21 02:06:03 -04:00
Joseph Doherty 45d08929e7 docs(index): LocalDb 0.1.2 + OtOpcUa Phase 1 adoption in the umbrella index
The lib row still claimed ScadaBridge was the only consumer (verified
2026-07-20); OtOpcUa's Phase 1 adoption merged 2026-07-21. Records 0.1.2 and
the wiped-peer snapshot fix it carries.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-21 01:24:09 -04:00
Joseph Doherty cad3bcb6bf fix(localdb): snapshot a wiped peer whose deltas were already acked and pruned
A converged pair prunes its oplog on ack, so "no oplog rows at all" is the
steady state of a healthy pair — not an anomaly. ComputeSnapshotRequiredAsync
measured the peer's gap against the oldest surviving oplog row and treated an
empty oplog as "no gap possible", which made that steady state the one state
from which a wiped peer could never be healed: it reconnected with an empty
database and a zero watermark, was told it needed no snapshot, and stayed
empty indefinitely.

With an empty oplog the oldest seq we could still stream is one past
last_acked_seq — ack-pruning is the only thing that empties the oplog without
also flagging needs_snapshot, and it deletes exactly seq <= last_acked_seq.
Measuring the gap against that heals the wiped peer and leaves every other
case identical: a converged peer's watermark equals last_acked_seq (no
snapshot), and a pair that has never written anything has both at zero.

Found by the OtOpcUa LocalDb Phase 1 live gate (check 4), which recorded it as
a documented limitation. Covered by a test that reproduces the live-gate
scenario through the real session stack: RED before this fix (the wiped side
never converges, 15 s timeout), green after. 148/148 pass.

Version 0.1.2.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-21 01:17:32 -04:00
Joseph Doherty c42348eff5 docs(localdb): the ScadaBridge adoption is merged, not pending
Phases 1 and 2 landed on ScadaBridge main together as PR #23
(merge 28ca04d7) on 2026-07-20 and were pushed to origin. The
component row still described both as unmerged branches.

Verified before editing: main..feat/localdb-phase1 and
main..feat/localdb-phase2 are both empty, main == origin/main,
and SiteReplicationActor/ReplicationService have no hits left in
main's tree.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-20 08:41:21 -04:00
Joseph Doherty 5836c79d3d docs(localdb): phase 2 complete + 0.1.1 in the component row
The row still said "Adopted by ScadaBridge (Phase 1 only)" and "Phase 2 is NOT
started". Both phases are now complete with a 10-check live gate PASS.

Also records what the row could not have said before: the 0.1.1 parent-
directory boot fix, that ScadaBridge is the library's ONLY consumer (verified —
OtOpcUa, mxgw and HistorianGateway have no LocalDb reference at all), the
deliberate never-registered status of notification_lists/smtp_configurations
and why, and the three operational constraints an operator has to know
(stop/start a pair together, the TombstoneRetention resurrection bound, and
MaxBatchSize batching by row count against a 4 MB gRPC cap).

Replication remains default-OFF and no production deployment has it enabled.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-20 05:38:02 -04:00
Joseph Doherty 10d076a9da test(localdb): sustained concurrent write load through pooled connections
Closes criterion 5 of ScadaBridge/docs/known-issues/2026-07-20-localdb-disk-io-
error-under-load.md §9: Phase 1 shipped only correctness and convergence tests,
so nothing exercised many pooled per-operation connections writing a REGISTERED
table (capture trigger + zb_hlc_next UDF) concurrently — which is exactly the
shape the ScadaBridge site nodes run under load.

8 writers x 250 inserts, one fresh pooled connection per operation, with
concurrent readers churning the pool and the WAL index throughout. Asserts both
that every write lands and that the oplog captured each exactly once, so a
trigger that dropped or double-counted under contention fails it.

Written during the 2026-07-20 disk-I/O incident investigation and left
uncommitted; the incident itself was root-caused to host-side sqlite3 access on
a bind-mounted WAL database, not a library defect.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-20 05:01:57 -04:00
Joseph Doherty 12e6f0d2c5 fix(localdb): create the database file's parent directory (0.1.1)
SQLite creates the database FILE on demand but never its parent DIRECTORY, and
SqliteLocalDb opens the file eagerly in its constructor — so a configured path
under a not-yet-existing directory was a hard startup failure ("SQLite Error
14: unable to open database file") rather than a first run that just worked.
Relative defaults like ./data/app.db hit it routinely; a containerized consumer
escapes only when a volume mount happens to create the directory first.

ScadaBridge found this during LocalDb Phase 2 and worked around it app-side
(SiteLocalDbDirectory.Ensure). Every other consumer still had the gap, so the
guarantee belongs here.

The standing objection to a library that creates directories is that it can
mask a mis-typed path by silently starting an empty database. That does not
apply: SQLite ALREADY does exactly that for a mis-typed file NAME. Refusing to
create the directory protects nothing — it only makes the two halves of one
path behave inconsistently and turns the directory half into an opaque error.

A creation failure (permissions, read-only mount) now throws an
InvalidOperationException naming the directory and the cause, instead of
surfacing as SQLite error 14. That is a change of exception type, but only on a
path that already failed hard.

Both behaviours are pinned and verified to fail with the call removed.
147 tests pass, 0 warnings. Published to the Gitea feed at 0.1.1.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-20 04:51:18 -04:00
Joseph Doherty baea6cc2e0 docs(secrets): interactive-console quickstart + discoverability sweep
- new task-first quickstart (deployment seeding + KEK-lockout walkthroughs)
- runbook: document the sixth ReferenceStatus (PresentUnverified) + quickstart link
- README + shared-contract + umbrella CLAUDE.md secrets row updated for 0.3.0 console
- CLI usage text now mentions the interactive console (was undiscoverable from --help)
2026-07-19 14:55:53 -04:00
Joseph Doherty 0139c90f89 docs(localdb): correct the adoption-design doc location in the LocalDb row
The design doc lives here in scadaproj, not in ScadaBridge; ScadaBridge holds
the Phase 1 plan and the Phase 2 gate.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-19 11:27:53 -04:00
Joseph Doherty 87ffe1b774 Merge branch 'worktree-secrets-interactive-cli' 2026-07-19 11:27:50 -04:00
Joseph Doherty 980b4a37f6 fix(secrets-cli): contain file-source key IO/access errors in doctor + bundle-import flows 2026-07-19 10:38:16 -04:00
Joseph Doherty 6dbb372adf docs(secrets): interactive console runbook + 0.3.0 version bump 2026-07-19 10:37:37 -04:00
Joseph Doherty 1f7d26d4d9 feat(secrets-cli): launch interactive console on bare secret in a TTY 2026-07-19 10:30:30 -04:00
Joseph Doherty 7e67bd61c7 fix(secrets-cli): doctor flow — contained old-key errors, corrupt-row + rewrap-failure coverage 2026-07-19 10:27:54 -04:00
Joseph Doherty 1b65e820fb test(secrets): serialize env-var-mutating test classes into one xunit collection
Environment.SetEnvironmentVariable/GetEnvironmentVariable mutate the
process-wide environ; concurrent setenv/getenv across parallel xunit test
classes is a documented crash/flake source on glibc even with unique
variable names. Group the six classes that touch process env vars into a
DisableParallelization=true collection so they run serially against each
other while everything else keeps running in parallel.
2026-07-19 10:27:09 -04:00
Joseph Doherty 04018aab6e fix(secrets-cli): bundle import — source-key verification, format gate up front, access-denied containment 2026-07-19 10:00:59 -04:00
Joseph Doherty 4549b93d2a fix(secrets-cli): doctor flow — catch scoped exactly to the rewrap call 2026-07-19 10:00:00 -04:00
Joseph Doherty e8b34be255 fix(secrets-cli): audit flow — cipher guard, shared actor helper, summary + branch coverage 2026-07-19 09:55:16 -04:00
Joseph Doherty d1ec0fe5da feat(secrets-cli): lockout-recovery flow — KEK diagnosis, guided rewrap, lost-KEK reset 2026-07-19 09:53:10 -04:00
Joseph Doherty 000d283c99 feat(secrets-cli): bundle export/import flows 2026-07-19 09:52:31 -04:00
Joseph Doherty 08c4ce5769 docs(localdb): ScadaBridge Phase 1 adopted - LocalDb component row truth pass
Was 'no app adoption yet'. Now records the honest state: ScadaBridge site nodes
adopted Phase 1 on an UNMERGED branch, replication wired but default-OFF and
live-proven on the docker rig's site-a pair only, Phase 2 not started, no other
app adopted, no production deployment replicating.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-19 09:51:55 -04:00
Joseph Doherty e5a4d0276a fix(secrets-cli): CRUD flows — escaped validation markup, shared prompt helpers, delete existence check 2026-07-19 09:47:10 -04:00
Joseph Doherty 6ad710bdbd test(secrets-cli): structural no-plaintext assert (base64 '+' JSON-escaping flake) + override doc note 2026-07-19 09:46:26 -04:00
Joseph Doherty 779f8a8d78 feat(secrets-cli): deployment seeding flow — audit ${secret:} refs and fill the gaps 2026-07-19 09:43:17 -04:00
Joseph Doherty fe3ea684f5 feat(secrets-cli): CRUD flows for the interactive console 2026-07-19 09:37:46 -04:00
Joseph Doherty 138e2c1006 fix(secrets-cli): bundle import — verbatim ApplyReplicated writes, format gate, entry-aware errors 2026-07-19 09:35:39 -04:00
Joseph Doherty 4576f73c4c fix(secrets-cli): KEK doctor — fresh-row verdicts, degraded rewrap guard test, vanished-row visibility 2026-07-19 09:33:53 -04:00
Joseph Doherty e60f2d5dad fix(secrets-cli): reference auditor — InvalidName containment, comment-key parity, name normalization 2026-07-19 09:27:13 -04:00
Joseph Doherty 21f6a0df92 fix(secrets-cli): shell — contain UnauthorizedAccess, flow-title guard, cancel-path test 2026-07-19 09:26:04 -04:00
Joseph Doherty e49496c856 feat(secrets-cli): interactive shell skeleton — target picker, degraded-KEK upgrade, flow dispatch 2026-07-19 09:16:06 -04:00
Joseph Doherty 6255409f16 feat(secrets-cli): ciphertext-only bundle export/import with LWW + cross-KEK rewrap 2026-07-19 09:14:43 -04:00
Joseph Doherty f0f2b23d03 feat(secrets-cli): KEK doctor — per-row diagnosis + guided rewrap remedy 2026-07-19 09:11:35 -04:00
Joseph Doherty 38d33cf4b7 feat(secrets-cli): reference auditor — classify every ${secret:} the target app needs 2026-07-19 09:11:21 -04:00
Joseph Doherty 9bc1e5852e fix(secrets-cli): degrade on malformed master-key source + topology note 2026-07-19 09:08:24 -04:00
Joseph Doherty 83af2b2eaf feat(secrets-cli): per-target session factory with degraded-KEK mode + literal KEK provider 2026-07-19 09:01:46 -04:00
Joseph Doherty b8c6c7d432 test(secrets-cli): clean up temp dirs in TargetConfigReaderTests 2026-07-19 08:54:54 -04:00
Joseph Doherty b9a57fe06e feat(secrets-cli): target config reader — operate on the app's own composed Secrets config 2026-07-19 08:50:52 -04:00
Joseph Doherty 1b013a56a7 feat(secrets-cli): recent-targets store for the interactive console 2026-07-19 08:50:03 -04:00
Joseph Doherty fe9d8865fe feat(secrets-cli): wire Spectre.Console + SqlServer store refs for interactive console 2026-07-19 08:48:22 -04:00
Joseph Doherty 7072dc25a2 docs(secrets): interactive console implementation plan (14 tasks) 2026-07-19 08:46:15 -04:00
Joseph Doherty a53671e0af docs(secrets): interactive CLI console design (approved) 2026-07-19 08:41:41 -04:00
Joseph Doherty fb5c41bd73 docs(localdb): ScadaBridge LocalDb adoption design (approved)
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-19 01:52:48 -04:00
Joseph Doherty cc7d0dbf18 docs(secrets): 0.2.3 rollout complete - all 4 apps bumped, modal gates PASS
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-19 01:28:15 -04:00
Joseph Doherty 7e7fbe9bf0 docs(secrets): scadaproj#2 fixed - Secrets.Ui 0.2.3 published, SB verified
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-19 01:11:40 -04:00
Joseph Doherty 62ab8f68d1 fix(secrets): ship the delete modal's own styles under collision-proof class names (0.2.3)
Fixes scadaproj#2. ConfirmDeleteModal used the bare `modal` class and the
Secrets.Ui RCL shipped no CSS at all, silently depending on the host having
no opinion about that selector. Bootstrap 5 does: `.modal { display: none }`
made the delete modal permanently invisible on every Bootstrap host
(ScadaBridge, OtOpcUa, HistorianGateway — confirmed live on the first two)
while every @onclick handler kept working. Only MxGateway, the lone
Bootstrap-free host, could ever have rendered it.

Fix, entirely inside the RCL so a package bump repairs every host with no
host-side changes:
- class vocabulary renamed to zb-secrets-modal / -backdrop / -card / -title
  so no host framework selector can match the elements;
- the component emits its own <style> block alongside the markup. Scoped
  .razor.css was deliberately NOT used: three of the four family hosts never
  link a scoped-CSS bundle, so isolation CSS would silently fail to load —
  the exact defect class being fixed. Theme tokens with fallbacks keep the
  card legible even on a host without the kit stylesheet.
- data-testids unchanged, so existing Playwright gates and bUnit tests keep
  their selectors.

New bUnit pins: no Bootstrap-reserved class name appears in the rendered
markup, and the component ships a style block that both positions the
overlay and gives it a display mode. Suite 182 pass / 0 fail / 0.2.3.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-19 01:08:08 -04:00
Joseph Doherty 0b23da429e docs(secrets): ScadaBridge#22 fixed + new Secrets.Ui modal-CSS defect (scadaproj#2)
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-19 00:59:28 -04:00
Joseph Doherty 03ff5cd8bc docs(secrets): lmxopcua#483 fixed - /admin/secrets interactive via host wrapper page
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-19 00:23:01 -04:00
Joseph Doherty fbb788d463 docs(secrets): clustered replication ENABLED + proven on the OtOpcUa docker-dev rig; #482 closed
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 16:01:15 -04:00
Joseph Doherty 8d9bcedaf3 docs(secrets): OtOpcUa on 0.2.2 - Akka gate re-run vs feed packages 6/6
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 15:04:17 -04:00
Joseph Doherty b077ca1b7a docs(secrets): 0.2.2 published to the Gitea feed (5 packages, restore-verified)
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 14:55:19 -04:00
Joseph Doherty 51bef634d0 test(secrets): make the context-after-await pin deterministic (fixes flake)
ActorContextAfterAwaitTests asserted that a ConfigureAwait(false)
continuation on the shared thread pool always throws NotSupportedException
when reading Self/Context. That property is a timing accident, not an Akka
guarantee: pool threads are exactly where Akka and the TestKit legitimately
install the [ThreadStatic] actor cell during mailbox runs and async
continuations, and Akka 1.5.62 has two non-throwing states besides — a
cleared cell makes ActorBase.Context return null (NullReferenceException on
.Self, not NotSupportedException) and ActorBase.Self return _clearedSelf
without any throw. Under parallel suite load the assertion failed once at
exactly that seam (2026-07-18); ironically the test's own doc comment said
the behaviour "does not reliably throw" and then asserted reliability.

The illegal reads now run on a dedicated new thread (LongRunning), the one
place the no-context state is guaranteed, while the realistic
ConfigureAwait(false) escape from the mailbox is kept. If the reads ever
unexpectedly succeed again, the failure message reports whose context the
thread was carrying. Verified 3 consecutive full-project runs green (38/38)
after 8 instrumented runs hunting the original repro.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 14:54:30 -04:00
Joseph Doherty a1df7ef26c fix(secrets): root-cause + fix the Akka replicator's hosted-process DI deadlock (0.2.2)
Closes the defect in scadaproj#1. The hang was never Akka: the package's DI
wiring closed a circular singleton dependency the container cannot see through
factory lambdas — ISecretStore (ReplicatingSecretStore decorator) ->
ISecretReplicator -> SecretReplicationActorProvider -> ISecretCacheInvalidator
-> DefaultSecretResolver -> ISecretStore. Resolution recurses around the loop
until MS.DI's StackGuard hops it onto a fresh thread-pool thread, which then
blocks forever on a singleton call-site lock the first thread still holds:
a silent permanent hang instead of a stack overflow. Managed stacks from
dotnet-dump show the repeating cycle and both parked threads; both candidate
causes in the issue (DistributedPubSub.Get vs the Lazy lock, missing
Akka.Cluster.Tools HOCON) are disproven — the actor constructor was never
reached, and the deadlock reproduces on a single non-clustered node.

Fix: defer the one cycle-closing edge. The provider now gets a
DeferredSecretCacheInvalidator that resolves the real invalidator on first
eviction — which only happens when a replicated row is applied, strictly after
graph resolution. Severing the edge instead is wrong: a null-invalidator
experiment ran the live gate at 5/6, with deleted secrets still resolving on
the peer. The SqlServer package never had the cycle (its replicator chain
never touches the invalidator), which is why the hub gate always passed.

Verified: live 2-node convergence gate now 6/6 (was: infinite hang), including
the delete-visibility check that proves the deferred invalidator really evicts.
New HostedProcessResolutionTests builds the graph as a host does (container-
registered ActorSystem, hosted services, watchdogged resolves) and fails on
0.2.1; DeferredSecretCacheInvalidatorTests pins the wrapper contract. Full
suite 180 passed / 0 failed / 15 skipped (env-gated live SQL).

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 14:39:40 -04:00
Joseph Doherty 57d2d193fc docs(secrets): link the Akka deadlock to its tracking issues
scadaproj#1 holds the defect (the library lives here); lmxopcua#482 is the
consumer-side tracker keeping Secrets:Replication:Enabled=false until it is fixed.
2026-07-18 14:13:23 -04:00
Joseph Doherty eb445ea7e7 docs(secrets): live convergence gate results - SQL hub PASSES 6/6, Akka FAILS
SQL-Server hub topology (ScadaBridge) is live-validated against a real SQL Server
2022 with two nodes: write->resolve via hub, tombstone propagation without
resurrection, bidirectional sweep, partitioned-node local resolution (site
autonomy - the reason hub mode was chosen), and wrong-KEK fail-closed via
SecretDecryptionException.

Akka peer-to-peer topology (OtOpcUa) FAILS the gate: resolving ISecretReplicator
hangs indefinitely in a real clustered process. Reproduced twice on a healthy
2-node cluster; isolated to constructing AkkaSecretReplicator -> ActorRef ->
system.ActorOf, NOT nested DI resolution. The library's own 2-node suite passes,
so the trigger is creation through DI in a hosted process. Root cause not yet
identified.

Impact: OtOpcUa would hang at startup if replication were enabled, since the
startup hook resolves ISecretStore. Harmless today only because the flag defaults
false. Do NOT enable Secrets:Replication:Enabled in OtOpcUa.

The gate did its job - it caught a blocking defect that every offline suite,
including the library's own real-cluster tests, had passed over.
2026-07-18 13:50:35 -04:00
Joseph Doherty 62a96e5f22 docs(secrets): reconcile 0.2.1 adoption - what was proven vs merely built
- All 4 apps on 0.2.1 (local branches, unpushed).
- Records the corrected security story: the version bump closed NO advisory (all four
  repos already resolved patched 2.1.12); the real live vulnerability was in ScadaBridge,
  masked by a NuGetAuditSuppress, and was fixed by separate work.
- Records the upstream 0.2.0 inert-Akka-replicator defect, its root cause (DI extensions
  with no container-building test - third instance of that class), and the 0.2.1 fix.
- Marks clustered topology WIRED-but-default-OFF and explicitly NOT live-validated;
  Task 9 remains open and the topology is not 'adopted' until it passes.
2026-07-18 12:21:31 -04:00
Joseph Doherty 6e8d346670 fix(secrets): Akka replication was inert in 0.2.0 - registration order bug (0.2.1)
AddZbSecretsAkkaReplication called AddZbSecrets FIRST, which does
TryAddSingleton<ISecretReplicator, NoOpSecretReplicator>(). The package's own
TryAddSingleton<ISecretReplicator> therefore found a descriptor already present
and was silently discarded.

Consequence: ISecretReplicator resolved to the no-op sink, so every write
published into nothing; and because SecretReplicationActor is only spawned as a
side effect of constructing AkkaSecretReplicator, no actor was ever created
either. No exception, no log line - a cluster that reports healthy and silently
never converges. The worst available failure mode for a secrets store.

Fix: register ISecretReplicator BEFORE AddZbSecrets, matching what the SQL-Server
package already did. Found during OtOpcUa adoption (Task 6), which is the first
code that ever built a container around this extension.

Root cause of the gap: the SQL-Server package had a DI test asserting its
replicator type (AddZbSecretsSqlServerTests:58) and the correct order; the Akka
package had neither. Every Akka test exercised the actor, serializer and
reconciler in isolation - none built a container, so nothing could see it. This
is the third instance of the same defect class in this library (the inert
ISecretReplicator seam, the unregistered concrete SqliteSecretStore, and now
this), all of which share one cause: unit tests that never construct the DI graph.

Adds AddZbSecretsAkkaReplicationTests (5 tests) asserting registration at the
ServiceCollection level. Verified to discriminate: with the 0.2.0 order restored,
2 of the 5 fail; with the fix, all 5 pass. They assert descriptors rather than
resolving from a provider on purpose - resolving ISecretReplicator eagerly spawns
the actor, whose PreStart needs DistributedPubSub and therefore a joined cluster,
which would make the test hang rather than fail.

Full suite Release-green: 175 passed, 15 skipped, no new warnings.
2026-07-18 11:36:45 -04:00
Joseph Doherty ccbdd4bcd1 docs: Secrets 0.2.0 published to the Gitea feed (5 packages, restore-verified)
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 04:46:14 -04:00
Joseph Doherty 15ef1f32a8 fix(secrets): anti-entropy never ran — Self read after await in the replication actor
I dismissed this finding from the code review as a false positive, reasoning
that Akka's ActorBase caches Self in a field and that three passing
anti-entropy tests traverse the path. Both premises were wrong. Self resolves
through Context, which is [ThreadStatic], and throws NotSupportedException once
a continuation resumes on a thread-pool thread.

The tests passed because a local SQLite store usually completes await
SYNCHRONOUSLY, so the continuation stayed on the mailbox thread and the context
was still intact. Correctness therefore depended on store latency and
thread-pool timing: green here, broken under a slower or contended store, with
the only symptom a per-peer warning every announce interval while nodes
silently stopped converging. The live-broadcast fast path masked it further —
only the anti-entropy repair path was dead.

Captures self on the actor thread and passes it in. Adds
GenuinelyAsyncSecretStore to force the async path, a regression test that fails
on the unfixed code (20s timeout) and passes in 3s after, and
ActorContextAfterAwaitTests pinning the underlying Akka behaviour so the wrong
assumption cannot be made again. Audited every remaining Self/Sender access in
the actor.

170 pass offline / 184 with the live SQL suite / 1 skip / 0 warnings.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 04:42:16 -04:00
Joseph Doherty dd0a846b64 feat(secrets): cluster replication via SQL Server and Akka.NET (G-7, 0.2.0)
Secrets were per-node SQLite, so a secret written on one node was invisible to
the rest of a cluster. G-7's design resolved the "shared SQL store vs Akka
replicator" fork to build only the former; both are built here so the choice is
a deployment decision (availability vs partition tolerance) rather than a
library limitation.

Two new packages — ZB.MOM.WW.Secrets.Replicator.SqlServer (shared store, plus a
local-store-with-hub mode) and .Replicator.AkkaDotNet (peer-to-peer over
distributed pub/sub). Core gains ISecretsStoreMigrator, one shared
SecretLastWriterWins predicate so no two stores can disagree on a tie, the
transport-agnostic reconciler, and ReplicatingSecretStore — which closes a real
gap: nothing had ever called ISecretReplicator.PublishAsync, so the seam was
inert and local writes would not have propagated at all.

Verified 182 pass / 1 skip / 0 warnings, including 15 live tests against a real
SQL Server 2022 (the SQLite suite ported case-for-case, so any behavioural
divergence between the stores fails) and a 9-test in-process 2-node Akka
cluster over real remoting. A post-build review caught six defects, all fixed
and now covered: both replication modes could not resolve from the container
(no test had built one), an unbounded fetch that broke past SQL Server's
2100-parameter cap, a poison row that aborted the rest of its batch forever,
Enum.Parse on peer input that could restart the actor in a loop, null crypto
blobs crossing the trust boundary, and a silently dropped pull-read failure.

Packed at 0.2.0 and vulnerability-scanned clean; not yet published to the feed.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 04:08:23 -04:00
Joseph Doherty e46060fada docs: record Auth 0.1.5 consumer bumps + the pre-existing AngleSharp build break
Closes out the security-fix rollout: mxaccessgw, ScadaBridge and HistorianGateway
are all on Auth 0.1.5 and pushed. Exposure was checked per repo rather than assumed --
only mxaccessgw and ScadaBridge actually resolved the vulnerable 2.1.11;
HistorianGateway already resolved 3.50.3, and OtOpcUa takes no ApiKeys/SQLite
dependency at all.

Also records two things worth not rediscovering: HistorianGateway's bump is
unverified by tests, and both it and ScadaBridge have a pre-existing AngleSharp
NU1902 error failing full-solution builds under TreatWarningsAsErrors.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 03:21:00 -04:00
Joseph Doherty 5e9cbd3ecf fix(deps)!: pin patched SQLitePCLRaw in Secrets + Auth; publish Secrets 0.1.3, Auth 0.1.5
Packing Secrets 0.1.3 surfaced NU1903: Microsoft.Data.Sqlite 10.0.7 pulls
SQLitePCLRaw.lib.e_sqlite3 2.1.11, which carries high-severity advisory
GHSA-2m69-gcr7-jv3q. Auth.ApiKeys had the same exposure and was already shipped
at 0.1.4 to three consumers, so both libs are fixed rather than only the one
being published.

Fixed the way ZB.MOM.WW.LocalDb already had it: CentralPackageTransitivePinningEnabled
plus a pin to the patched 2.1.12. Bumping Microsoft.Data.Sqlite does not help --
even 10.0.10 still resolves 2.1.11 -- so the pin is the actual fix. The pin reaches
consumers: both nuspecs now declare SQLitePCLRaw.lib.e_sqlite3 >= 2.1.12 as a direct
dependency, verified by restoring the published packages into a scratch project,
which resolves 2.1.12 and scans clean.

Auth goes 0.1.4 -> 0.1.5 with no API change (0.1.4 plus the pin). Suites re-run
after the native-lib swap with identical counts, so no behavioral regression:
Secrets 97 pass/1 skip, Auth 215 pass/1 skip (both skips are Windows-only DPAPI
and opt-in LDAP).

Consumers are NOT yet bumped and remain on vulnerable versions: mxaccessgw 0.1.4,
HistorianGateway 0.1.4, ScadaBridge 0.1.3. Secrets consumers all sit at 0.1.2 and
also lack KEK rotation.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 03:14:25 -04:00
Joseph Doherty 3dd7aa40ff docs: publish LocalDb 0.1.0 to the feed + reconcile component status against verified state
Publishes the three ZB.MOM.WW.LocalDb packages to the Gitea feed (restore-verified
from a scratch consumer) and adds the build/push.sh the other shared libs already have.

The status prose across CLAUDE.md, README.md and components/*/GAPS.md had drifted from
reality, so it was re-derived from the feed listing and the actual PackageReferences +
registration calls on each consumer's default branch rather than from prior claims.
Five claims were false: Health "not yet adopted" (all four apps wire MapZbHealth),
GalaxyRepository's mxaccessgw adoption "a follow-on" (its Server wires
AddZbGalaxyRepository), Configuration "not yet pushed", Secrets G-8 "not yet
committed", and Theme pinned at 0.2.0 (all four are on 0.3.1). Every doc also said
"three apps" while HistorianGateway is a fourth consumer of seven libs, and all
eight libraries' test counts were stale (re-ran each suite; all green).

Surfaces one previously unrecorded gap: Secrets source is at 0.1.3 with KEK rotation
committed, but the feed tops out at 0.1.2, so no app can consume rotation until it
is published.

Health and observability divergence tables are labelled historical, not re-verified —
the libraries are proven wired, but per-app probe coverage vs spec was not re-walked.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 03:06:49 -04:00
Joseph Doherty 9cb6831380 docs(localdb): mark all 15 plan tasks completed
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 01:20:29 -04:00
Joseph Doherty de65ca2b5d polish(localdb): final integration-review fixes — drift XML doc, trim core deps, metrics doc/encapsulation
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 01:20:08 -04:00
Joseph Doherty ac6bcde159 docs(localdb): README + scadaproj index row + design-doc deltas; pack-verified 3 nupkgs @ 0.1.0
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 01:12:19 -04:00
Joseph Doherty b2345c32d4 test(localdb): convergence polish — provable LWW race arbitration, collection serialization, dead-letter diagnostics
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 01:06:00 -04:00
Joseph Doherty c5352f3ed8 feat(localdb): periodic oplog maintenance service (caps enforcement + tombstone pruning, both roles)
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 01:02:06 -04:00
Joseph Doherty 154d584190 fix(localdb): capture triggers survive consumer upserts (explicit ON CONFLICT upsert form, outer-statement override) 2026-07-18 00:57:27 -04:00
Joseph Doherty 801b042208 test(localdb): bidirectional convergence + randomized property tests
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 00:51:16 -04:00
Joseph Doherty eb40cd8f29 fix(localdb): telemetry review fixes — meter naming, snapshot status, session-count Connected
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 00:14:57 -04:00
Joseph Doherty be4ca76f5f feat(localdb): telemetry meters + ISyncStatus
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-18 00:03:39 -04:00
Joseph Doherty 8befebd476 fix(localdb): snapshot review fixes — MAX-guarded complete watermark, keyset pagination, phantom-row guard
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-17 23:50:42 -04:00
Joseph Doherty 130e9c918f feat(localdb): snapshot resync (LWW-merging, tombstone-carrying, delta resume)
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-17 23:35:50 -04:00
Joseph Doherty e92cdc6d3a fix(localdb): adapter review fixes — deterministic pump teardown, always-hosted initiator, backoff clamp
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-17 23:13:02 -04:00
Joseph Doherty a64fc26391 feat(localdb): gRPC sync adapters, background service, replication DI
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-17 23:01:29 -04:00
Joseph Doherty 183901e8ac test(localdb): pin drift-watermark branch; guard writer loop against completed-lane spin 2026-07-17 22:50:33 -04:00
Joseph Doherty 92ccbac8db fix(localdb): sync session concurrency fixes — two-lane writer, teardown fault fidelity, per-entry drift, gated snapshot seam 2026-07-17 22:44:42 -04:00
Joseph Doherty 925623b878 feat(localdb): SyncSession protocol state machine (handshake fail-closed, bidirectional delta pump) 2026-07-17 22:26:03 -04:00
Joseph Doherty b223507070 fix(localdb): applier review fixes — null-row_json guard, clock recovery via last_seen_hlc, fidelity + guard tests
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-17 22:15:51 -04:00
Joseph Doherty d7cbdce65c feat(localdb): LWW applier (hlc+node_id tie-break, applying guard, dead-letter, atomic watermark)
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-17 22:03:24 -04:00
Joseph Doherty 3cf8cabaf9 fix(localdb): oplog store review fixes — ack clamping, age-based pruning, monotonicity tests
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-17 21:55:25 -04:00
Joseph Doherty 4f9982c53f fix(localdb): DI review fixes — onReady leak guard, BusyTimeoutMs ctor guard, shared allow-list 2026-07-17 21:47:28 -04:00
Joseph Doherty 529585163c feat(localdb): oplog store (batch read, ack watermark, pruning caps, tombstone retention)
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-17 21:45:20 -04:00
Joseph Doherty c061ba733f feat(localdb): options validation + AddZbLocalDb DI; fail-fast on unsupported parameter collections 2026-07-17 21:40:23 -04:00
Joseph Doherty 3d72d2ee4b test(localdb): pin the S2 stale-rowid guard (in-txn + mixed multi-row PK-change regression tests) 2026-07-17 21:37:11 -04:00
Joseph Doherty df2518611f fix(localdb): capture-layer review fixes — BLOB fail-closed, identifier escaping, master lock, PK-change tombstone, digest canon 2026-07-17 21:30:45 -04:00
Joseph Doherty f4063f811f feat(localdb): opt-in table registration + capture triggers (oplog + row_version, applying guard) 2026-07-17 21:18:08 -04:00
Joseph Doherty 8b921e3106 feat(localdb): localdb_sync.v1 wire contract 2026-07-17 21:12:25 -04:00
Joseph Doherty 12b8839f33 fix(localdb): Task 4 review fixes — synchronous allow-list, dictionary params, async conn setup, dispose guard 2026-07-17 21:11:07 -04:00
Joseph Doherty 827bf44684 test(localdb): review fixes — index assertion, AUTOINCREMENT rationale, ReadMeta guard, concurrent HLC test 2026-07-17 21:05:10 -04:00
Joseph Doherty 83f384247c feat(localdb): SqliteLocalDb host (WAL, UDF-registered connections, HLC recovery, consumer SQL API) 2026-07-17 21:03:39 -04:00
Joseph Doherty fb8f751fac feat(localdb): lib-owned schema (meta/oplog/peer_state/row_version/applying/dead_letter) 2026-07-17 21:00:04 -04:00
Joseph Doherty cf58077398 feat(localdb): hybrid logical clock (UTC-ms<<16 | counter) 2026-07-17 20:58:02 -04:00
Joseph Doherty 61e5564c26 feat(localdb): scaffold ZB.MOM.WW.LocalDb (core/contracts/replication + tests)
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-17 20:55:56 -04:00
Joseph Doherty 9cef3c5d45 docs(localdb): implementation plan (15 TDD tasks) + task tracking
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-17 20:31:45 -04:00
Joseph Doherty bf4c5dccbd docs(localdb): approved design for ZB.MOM.WW.LocalDb (embedded SQLite cache + optional 2-node bidirectional async gRPC replication)
Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
2026-07-17 20:25:22 -04:00
Joseph Doherty d82d3451e7 feat(secrets): build G-8 KEK rotation (RewrapAll); design+plan G-7 clustered replication
G-8 (KEK rotation) — built in ZB.MOM.WW.Secrets, lib 0.1.2->0.1.3:
- ISecretCipher.Rewrap(row, oldKek, newKek): re-wraps the per-secret DEK only
  (bodies never re-encrypted; revision/timestamps preserved -> invisible to
  cluster LWW). Fail-closed on wrong old-KEK id, wrong key bytes, and malformed
  wraps; DEK zeroed on all paths.
- ISecretStore.ApplyRewrapAsync(rewrappedRow, expectedCurrentWrappedDek):
  updates only the 4 wrap columns + kek_id, compare-and-swap on the current
  wrapped DEK so a concurrent set/rotate cannot corrupt a row (closes a
  review-caught TOCTOU).
- KekRotationService.RewrapAllAsync + RewrapReport: enumerate all rows incl.
  tombstones, idempotent/resumable skip-already-current, bounded CAS-retry,
  fail-closed on unknown/identical KEK.
- `secret rewrap-all` CLI verb: key material only via env-var name / file path,
  JSON counts report; README section + operator runbook.

Verified: full offline suite green (82 core + 15 UI, 0 regressions) + end-to-end
CLI smoke + adversarial crypto review (all 7 categories PASS; TOCTOU fixed).

G-7 (clustered replication) — designed + planned, no code:
- Fork resolved to build Option A (shared SQL-Server ISecretStore); Akka
  replicator ZB.MOM.WW.Secrets.Akka is a deferred phase-2. Design doc +
  executable plan + .tasks.json under docs/plans/2026-07-17-secrets-g7-*.

Tracking: components/secrets/GAPS.md + CLAUDE.md secrets row updated.
2026-07-17 02:55:43 -04:00
Joseph Doherty b009507e10 docs(secrets): OtOpcUa G-2 live-proven vs prod MxGateway (wonder-app-vd03:5120)
Record the OtOpcUa live wonder gate (item 2). A throwaway harness drove OtOpcUa's
real GalaxyDriverBrowser (secret: ApiKeySecretRef resolved via ISecretResolver) against
the real production MxGateway: dummy secret: ref -> MxGatewayAuthenticationException,
real metadata:read key -> CONNECTED + browsed the real Galaxy root (10 nodes). Temp key
minted via the dashboard, then revoked (functionally proven) + deleted; no prod key
touched; harness + scratch stores destroyed. All four apps now G-2..G-6 done + live-proven.
2026-07-16 23:15:00 -04:00
Joseph Doherty 1d05ecdf1e docs(secrets): OtOpcUa adoption executed + merged (lmxopcua @872cf7e3) — all 4 apps done
Record the OtOpcUa secrets adoption (G-2/G-4/G-5/G-6, the last app): FF-merged +
pushed to lmxopcua origin/master @872cf7e3. Update the components/secrets/GAPS.md
OtOpcUa bullet (execution record + the three verified plan deviations + the regression
the gate caught) and the CLAUDE.md secrets-component-table row. All four apps
(HistorianGateway, mxaccessgw, ScadaBridge, OtOpcUa) now adopt ZB.MOM.WW.Secrets.
2026-07-16 22:52:21 -04:00
Joseph Doherty c6b782e635 docs(secrets): re-verify OtOpcUa adoption plan vs v3.0 master (ec6598ce)
The v3.0 dual-namespace rewrite (PR #472) moved anchors and reshaped the
build, so the plan is refreshed to stay executable: CPM correction (OtOpcUa
is on Central Package Management, not inline versions), OpcUaClient options
in .Contracts + GalaxyDriverBrowser in .Browser, DriverHostActor line
shifts, and appsettings/owner precision. Driver-secret flow itself was
untouched by v3.0, so the two-layer approach holds.
2026-07-16 16:50:14 -04:00
Joseph Doherty 5eea386ebf docs(secrets): ScadaBridge G-3/G-4/G-5/G-6 adopted + merged + live-proven (ScadaBridge @ 128f1596) 2026-07-16 16:15:28 -04:00
Joseph Doherty fbb79ef83a docs(index): OtOpcUa v3.0 — dual-namespace address space (PR #472 merged)
Update the OtOpcUa umbrella entry for v3.0: the single .../ns namespace is
replaced by .../raw (s=<RawPath>) + .../uns (s=<Area>/<Line>/<Equipment>/<Eff>),
single-source fan-out to both NodeIds, Organizes UNS->Raw, writes/HistoryRead via
either NodeId, multi-notifier alarms, EquipmentNodeIds retired. Flags the wire-
contract change as a pending ScadaBridge Data-Connection-Layer cutover.

Claude-Session: https://claude.ai/code/session_01LVneM3eh1UtJxEisFXgmox
2026-07-16 14:39:33 -04:00
Joseph Doherty d95328efb3 docs(secrets): mxaccessgw G-4/G-5/G-6 adopted + merged (mxaccessgw @ e088dfa) 2026-07-16 13:49:43 -04:00
Joseph Doherty 6be5f746d5 docs(secrets): G-2..G-6 adoption design + 3 per-repo plans
Shared design (two resolution layers, wiring template, master-key/clustering
fork) + per-repo executable plans with code-verified anchors and co-located
.tasks.json:
  - mxaccessgw (G-4/G-5/G-6, 8 tasks)
  - otopcua    (G-2/G-4/G-5/G-6, 10 tasks, 2 slices)
  - scadabridge (G-3/G-4/G-5/G-6, 10 tasks, 2 slices)
Linked from components/secrets/GAPS.md.
2026-07-16 09:19:33 -04:00
Joseph Doherty e347286f28 docs(components): normalize Secrets component + index the shared lib
Add components/secrets/ (SPEC, realized shared-contract, code-verified
current-state for OtOpcUa/mxaccessgw/ScadaBridge, GAPS adoption backlog) and
register the Secrets row in CLAUDE.md + components/README.md. The
ZB.MOM.WW.Secrets lib is built + published 0.1.2 + reference-consumer-proven
(HistorianGateway, live vs the wonder historian); per-app adoption is the
tracked follow-on.
2026-07-16 04:49:57 -04:00
Joseph Doherty de77bc30e3 merge: ZB.MOM.WW.Secrets envelope-encrypted secrets manager (lib + Blazor UI + CLI)
7th shared ZB.MOM.WW.* library: AES-256-GCM envelope-encrypted secret store
(ISecretStore/SQLite), pluggable IMasterKeyProvider, ${secret:name} config
resolution, ISecretResolver runtime cache, Blazor /admin/secrets management UI
on the Theme kit, and a headless 'secret' CLI. Published 0.1.2 to the Gitea feed;
HistorianGateway adopted as reference consumer (live-proven end-to-end against
the real wonder historian). 80 tests pass.
2026-07-16 04:44:01 -04:00
Joseph Doherty 9bd3c76d96 fix(secrets): ${secret:} expander skips comment keys (_-prefixed leaf) — 0.1.2
Live HistorianGateway boot caught that the expander scanned a '_secretsComment' appsettings
value documenting the ${secret:...} syntax, tried to resolve the literal example token, and
crashed boot. The family uses _*Comment keys pervasively, so skip any config key whose leaf
segment starts with '_' (the _comment convention). Functional keys never lead with '_'.
2026-07-16 04:16:25 -04:00
Joseph Doherty 76124590f0 fix(secrets-ui): admin role must be canonical 'Administrator' (case-sensitive) — 0.1.1
Reference-consumer (HistorianGateway) caught that SecretsAuthorization.AdminRole was
'administrator' (lowercase) while the family canonical role is CanonicalRole.Administrator.
ASP.NET role claims compare case-sensitively (Ordinal), so a real admin got 403 on the
secrets UI. Now nameof(CanonicalRole.Administrator).
2026-07-16 04:11:20 -04:00
Joseph Doherty 2c64683303 docs(secrets): package README + embed in nupkgs 2026-07-16 04:00:32 -04:00
Joseph Doherty e20812cbae chore(secrets): wire cache invalidation on rotate/delete, drop dead RevealEnabled, remove scaffold leftovers 2026-07-15 17:39:55 -04:00
Joseph Doherty 294f53b49a fix(secrets-ui): preserve metadata on rotate + audit unexpected mutation/reveal failures 2026-07-15 17:31:34 -04:00
Joseph Doherty 0ab276dac0 feat(secrets-cli): set/get/list/rm/rotate commands 2026-07-15 17:26:14 -04:00
Joseph Doherty 21556cc1a7 feat(secrets-ui): add/rotate/delete modal + audited gated reveal 2026-07-15 17:20:01 -04:00
Joseph Doherty d7f8ca455b feat(secrets-ui): RCL + authz policies + metadata-only secrets list 2026-07-15 17:10:40 -04:00
Joseph Doherty 7f1db1b214 feat(secrets): SecretsOptions + AddZbSecrets DI + migration hosted service 2026-07-15 17:05:30 -04:00
Joseph Doherty 8c4175d8ce fix(secrets): audit decryption failures in resolver (fail-loud, no plaintext) 2026-07-15 17:01:10 -04:00
Joseph Doherty 0bb553212a feat(secrets): ${secret:} config expander (fail-closed) 2026-07-15 16:58:34 -04:00
Joseph Doherty 79ebd14baa feat(secrets): default resolver with TTL cache + audit (never logs plaintext) 2026-07-15 16:55:24 -04:00
Joseph Doherty 10455ec53b feat(secrets): sqlite secret store (overwrite-in-place, tombstone, manifest, LWW) 2026-07-15 16:50:59 -04:00
Joseph Doherty e99a8731e9 feat(secrets): sqlite connection factory + schema v1 + migrator 2026-07-15 16:46:15 -04:00
Joseph Doherty 1c13b4af99 feat(secrets): pluggable master-key providers (env/file/dpapi) + factory 2026-07-15 16:43:10 -04:00
Joseph Doherty 01911508b9 fix(secrets): harden SecretName (reject rooted paths, fail-fast on default) + keep SecretDecryptionException sealed 2026-07-15 16:37:21 -04:00
Joseph Doherty b784c7117f feat(secrets): AES-256-GCM envelope cipher with AAD binding 2026-07-15 16:34:46 -04:00
Joseph Doherty 16b32257f5 feat(secrets): abstractions seam interfaces 2026-07-15 16:30:19 -04:00
Joseph Doherty d78b533045 feat(secrets): abstractions value types, enums, exceptions 2026-07-15 16:28:11 -04:00
Joseph Doherty 824facab39 feat(secrets): scaffold ZB.MOM.WW.Secrets solution + 4 projects 2026-07-15 16:24:38 -04:00
1602 changed files with 391656 additions and 1870 deletions
@@ -0,0 +1,16 @@
---
name: sister-project-history
description: Use when you need the detailed change history, live-gate records, redundancy/auth/ACL behaviour, or ScadaBridge consumer-impact notes for a sister project (OtOpcUa, HistorianGateway, BTDB) — the scadaproj root CLAUDE.md keeps only a short summary row per project; the full narrative lives in this directory.
---
# Sister project history
The root `CLAUDE.md` index keeps one short row per sister project. The full narrative rows that used to live
in that table were moved here **verbatim** on 2026-09-03 (they were ~57k characters loading into every session):
- `otopcua.md` — OtOpcUa: v3 dual-namespace address space, every driver, redundancy/mesh program, data-plane auth + ACL enforcement, deferment register, the authoring-vs-deploy-gate parity arc, and the per-issue consumer-impact record for ScadaBridge.
- `historiangateway.md` — HistorianGateway: ArchReview cycles, pending.md items, session pools, datatype gaps, SQL-path workarounds, PR/commit history.
- `btdb.md` — BTDB (Batch Tracking Database, added 2026-09-03): schema + sproc write contract, Historian/CLR coupling, Galaxy/MESAPI/ScadaBridge edges, the DARS `BatchTracker_DB` fork, and the gap analysis.
Read the file for the project you are working against. When a sister repo tells you to "update its entry in
`scadaproj/CLAUDE.md`", append the detail to the file here and keep the index row to a few lines.
@@ -0,0 +1,207 @@
# BTDB (Batch Tracking Database) — index history + analysis
> Added 2026-09-03 as a sister project. **This file is the authoritative place for BTDB detail — append here and keep the root index row short.** Everything below was verified from source on 2026-09-03 unless marked _(inferred)_.
| Project | Location | Stack | Repo | Summary |
|---|---|---|---|---|
| **BTDB** (Batch Tracker) | `~/Desktop/btdb` (case-insensitive FS: also `BTDB`) | SQL Server 2016+ SSDT project + SQL CLR (net472) · manager: **Blazor Web App net10.0** on `feat/manager-blazor` (§8; `master` still carries the EOL net6.0 MVC app) | **`ZimmerBiomet/BTDB`** on the corporate Gitea `wonder-app-vd03.zmr.zimmer.com:3000` (`master` @ `d147c10e`, 2023-07-26). **Not** on `gitea.dohertylan.com`. | The `BT` SQL Server database that is the plant's **batch/cycle/work-order system of record for data collection**: Galaxy machine objects call its `StartMachineBatch`/`StartMachineCycle`/`End*`/`AddMachineBatchWorkOrder`/`AddOtherData*` sprocs; reports pull time-series per batch out of the AVEVA Historian through its CLR sprocs (`OPENQUERY(INSQL, … WideHistory …)` + `Runtime.dbo.*`); MESAPI and ScadaBridge's inbound API resolve `SAPID → Machine.Code` from `dbo.Machine`. `BTDBManager` is a small Windows-service MVC site for machine/group config, batch edits (audited) and cross-environment config import. |
## 1. What is on disk, and where the truth is
- `~/Desktop/btdb` is **not a git checkout** — no `.git`, no `CLAUDE.md`, no `README`. It is a file-for-file snapshot of `ZimmerBiomet/BTDB` `master` (the only branch) at its head commit `d147c10e` (2023-07-26, "Update notification system tables to add urgent flag"). Verified by comparing the Gitea tree with the local tree: 170 vs 168 files, the only difference being the remote's `.gitattributes`/`.gitignore`. The repo's `updated_at` of 2024-11-07 is not a commit (the branch head is still 2023-07-26).
- `~/Desktop/DARS/WW_ARCH/BatchTracker_DB/` is a **fork of the `Database` project only** (no Manager), modified 2026-08-13, also not under git (DARS is not a repo). Substantive differences vs the snapshot, all matching the DARS sprint-1 spec `DARS/sprints/sprint1/bt_db_changes.md`:
- new table `MachineBatchTransfer` (source/dest batch chain for mid-run reactor failure; `TransferType` CHECK `'mid_run_failure'`; three indexes) + sproc `AddMachineBatchTransfer` (linear-chain guard);
- `MachineBatchWO` gains `ContainerID NVARCHAR(64) NULL` + `MoveOutTimestamp DATETIME2 NULL` with filtered indexes (Camstar container traceability; mirrors the `SAPID`/`ZTag` idiom);
- new CLR sproc `GetLinkedBatchTSV` (+ `_Wrapper`) that walks the transfer chain and stitches TSVs, and `LinkedBatchAlarm_Wrapper`;
- `StartMachineBatch.sql`, `MachineBatch.sql`, `AuditLogMachineBatch.sql` differ **only** in BOM/CRLF → LF normalization (no logic change).
- Reference doc for the schema: `DARS/WW_ARCH/BatchTracker_Reference.md` (states 22 tables / 35 SQL sprocs / 4 CLR sprocs / 5 CLR UDFs / 6 table types / 1 aggregate).
- **Resolved 2026-09-03 — the divergence is closed locally:** `~/Desktop/btdb` was turned into a real checkout (`git init` + fetch of `ZimmerBiomet/BTDB`, `master` tracking `origin/master`; the snapshot was tree-identical apart from exec bits copied from Windows, which were cleared). The DARS fork's transfer-chain work was migrated onto branch **`feat/machine-batch-transfer`** as one commit: the five new objects, the two `MachineBatchWO` columns, and the `.sqlproj` wiring **including the `Compile` entry for `GetLinkedBatchTSV.cs` that the fork had omitted** (without it the CLR sproc is never built and its wrapper fails at deploy). The BOM/CRLF re-saves were not carried over. The sprint-1 plan (`bt_db_changes.md`, overview, diagrams) and `BatchTracker_Reference.md` now live under `btdb/docs/`. **The branch is local only — not pushed to the corporate Gitea.** `DARS/WW_ARCH/BatchTracker_DB/` is now superseded and should be deleted or replaced by a pointer once the branch is pushed. A second commit on the same branch carried the two columns through the Manager's batch-edit path: `MachineBatchWOType` (appended last — the TVP binds by ordinal and `ToDataTable` emits properties in declaration order, so the view model's property order must keep matching), `AuditLogMachineBatchWO` (`Prev_`/current pairs), the DTOs and view model, `SaveBatchEdit.sql` (MERGE change-detection with `COALESCE` because both columns are NULL-able, OUTPUT and the three audit inserts), and the Kendo work-order grid in `Views/BatchEdit/Edit.cshtml` (masked timestamp editor like the cycle grid). `LookupBatchInfo.sql` is `SELECT *` so it needed nothing. Not touched: the Telerik `BatchEditAuditLogReport.trdp` (binary package; open it in the Telerik designer to add the audit columns) and the batch search grid (`SearchBatches.sql`), which still lists only work-order numbers. Nothing here was built or run: the Manager needs Telerik + Windows, and the SSDT project needs MSBuild; a throwaway compile of the Manager retargeted to .NET 10 on the Mac showed no errors in the touched files.
## 2. Solution shape
`BTDB.sln` (VS 2022) = two projects:
| Project | Kind | Notes |
|---|---|---|
| `Database/Database.sqlproj` | SSDT, `Sql130DatabaseSchemaProvider` (SQL Server 2016+), CLR assembly targets **net472**, C# namespace `BT` | 22 tables, 6 table types, ~35 T-SQL sprocs, 3 CLR sprocs (`GetTSV`, `GetMachineBatchTSV`, `GetCycleTSV`), 5 CLR UDFs (`GetAggregateValues`, `CheckTriggered`, `WhenTriggered`, `WhenCleared`, `StringCompare`), 1 CLR aggregate (`StringJoin`), 1 T-SQL TVF (`GenerateShifts`), 1 trigger (`TrgNotification` → `AuditLogNotification`). Requires `CLR enabled` on the instance. |
| `Manager/BTDBManager.csproj` (**`master` only — deleted on `feat/manager-blazor`, see §8**) | ASP.NET Core MVC, **net6.0** (out of support since 2024-11), Dapper 2.0, `System.Data.SqlClient`, `System.DirectoryServices` (Windows-only LDAP), `Microsoft.Extensions.Hosting.WindowsServices`, Kendo UI + Bootstrap, **Telerik Reporting R2 2022** referenced by an absolute `HintPath` into `Program Files (x86)` | Kestrel `http://*:9876`; runs as a Windows service; 13 embedded `.sql` query resources; 3 `.trdp` Telerik audit reports. `Manager/install.bat`/`uninstall.bat` are **leftovers from a different service** (`WWNotificationSystem.exe`) and do not install the Manager. |
## 3. Database model (what the family writes and reads)
**Core hierarchy:** `Machine` (`Code` unique; optional unique `ZTag`, `SAPID`; `TimeZone`; `MultipleBatch`/`MultipleCycle` flags; `OtherData` JSON) → `MachineBatch` (start/end operator + UTC timestamps, `OtherData`) → `MachineCycle` (same shape) and `MachineBatchWO` (`WorkOrderNumber`, `ItemNumber`). `MachineGroup` + `MachineGroupMembership` give roll-ups (DARS models one `Machine` per reactor *side*, one `MachineGroup` per unit). `MachineAlarm` is a per-machine alarm catalog (`Severity` 0–999, `FlaggedForMES`).
**Lifecycle sprocs (the write contract):**
| Sproc | Behaviour |
|---|---|
| `StartMachineBatch(@Code, @OperatorID, @o_MachineBatchID OUT)` | Looks up machine by `Code`; unless `MultipleCycle`/`MultipleBatch`, **auto-closes** any open cycle/batch first; inserts with `GETUTCDATE()`. Throws 50000 if machine unknown. |
| `EndMachineBatch(@MachineBatchID, @EndOperatorID)` | Closes the open cycle too; throws if not found / already closed. |
| `StartMachineCycle(@MachineBatchID, @OperatorID, @o_MachineCycleID OUT)` / `EndMachineCycle` | Cycle must belong to an open batch. |
| `AddMachineBatchWorkOrder(@MachineBatchID, @WorkOrderNumber, @ItemNumber, @o OUT)` | Only on open batches. |
| `AddOtherDataMachineBatch` / `…MachineBatchWorkOrder` / `…MachineCycle (@ID, @DataKey, @DataValue)` | `JSON_MODIFY` into `OtherData` — via **dynamic SQL that concatenates `@DataKey`/`@DataValue`** into the statement (`sp_executesql` of a built string). Injection surface; callers today are trusted Galaxy scripts. |
All timestamps are `GETUTCDATE()`; `Machine.TimeZone` is used only at retrieval time (`wwTimeZone=` in report wrappers). This matches the family's all-UTC rule.
**Historian coupling (the read contract):** the CLR code resolves a machine-relative tag (`<Code>.<local>`; `*.<attr>` shorthand; `|literal|` static columns) to the Historian's global tagname via `Runtime.dbo.TagExtendedPropertyInfo` (`HierarchicalName`), then runs `SELECT … FROM OPENQUERY(INSQL, 'SELECT DateTime, [tag]… FROM WideHistory WHERE … wwTimeZone="UTC" AND <queryParams>')` (`wwRetrievalMode`, `wwResolution`, `wwTimeZone` are passed through **verbatim** from `@queryParams`). Discrete checks read `Runtime.dbo.DiscreteHistory`; alarm wrappers read `Runtime.dbo.Events` (`IsAlarm=1`, `Alarm_OriginationTime`, `Alarm_DurationMs`, `Alarm_UnAckDurationMs`). **Consequence: the `BT` database must live on (or three-part-name-reach) the Historian's SQL instance with the `INSQL` linked server** — it is co-tenant with `Runtime`, which is why it sits on the `wonder-sql-*` boxes.
**Report wrappers** are per machine family and are the consumers of the CLR layer: Crest (`CrestWide`/`CrestMinMax`/`CrestAlarm`/`CrestCleaner*`), Elma (`ElmaData`, `Elma_Bulk_Query_Nitric`), `ExtruderWide`, `PultrusionWide`, Haas (`HaasStatusReport`, `HaasAlarm`, `QV_Haas*` = QlikView), Solar (`SolarAlarms`/`SolarEvents`), DryHeat (`DryHeatCycleReport`/`Search`/`BulkReport`), PoncePolyPress, `Z002432Wide`/`Z002433Wide`. `GenerateShifts` builds a 3-shift calendar table for these.
**Auth tables that are not the Manager's:** `UserAuth`, `UserAuthDetails`, `UserAuthRole`, `ApiKey` are ServiceStack's schema — they belong to **MESAPI/WWSupport** (the Camstar-facing REST service, see `mes-delmia-integration-api.md` §1.1: `ApiKeyAuthProvider` + `LdapAuthProvider`, role `MESAPI`), which shares the `BT` database. The Manager authenticates via LDAP only.
**Notification tables** (`Notification`, `NotificationLog`, audited by trigger) back the separate `WWNotificationSystem` Windows service, which is **not in this repo**.
## 4. BTDBManager (the config/edit UI) — `master` state; the replacement is §8
- **Auth:** cookie scheme; `LdapAuthenticationService` binds `LDAP://nam.zimmer.com` with the user's own credentials via `System.DirectoryServices` (so it only runs on a domain-joined Windows host), reads `memberOf`, and keeps only the three configured group DNs. Policies `READONLY` / `MACHINECONFIG` / `BATCHEDIT` map to `ReadOnlySecurityGroup` / `MachineConfigSecurityGroup` / `BatchEditSecurityGroup`; the checked-in DEV config points all three at `UG_WW_APP_ADMIN_DEV`. A global `AuthorizeFilter` makes every controller (incl. `/Api/GetMachines`, `/Api/GetMachineGroups`) require login. This is exactly the AD-group→role problem the family's `ZB.MOM.WW.Auth` 0.3.0 + `ldap_mapping.md` already solve.
- **Features:** Machine CRUD (with group memberships + alarm catalog via TVPs `MachineGroupMembershipType`/`MachineAlarmType`), MachineGroup CRUD, batch search/edit (`SaveBatchEdit` writes `AuditLogBatchEdit` + prev/new `AuditLogMachineBatch`/`…WO`/`…Cycle` rows), **MachineConfigImport** (copies machine/group config from another environment's `BT` — sources `QA` and `PROD` are hard-wired in `appsettings.json`), and Telerik `.trdp` audit reports.
- **Secrets are checked in:** `appsettings.json` carries plaintext `wonderapp` SQL passwords for DEV/QA/PROD, and `install.bat` carries a domain service-account password. Treat all of them as compromised-by-repo; do not copy them into any other file or reply. This is the pattern `ZB.MOM.WW.Secrets` (`${secret:}`) exists to replace.
- **Environment hosts as recorded in 2023:** DEV `wonder-sql-vd01/BT`, QA `wondersqlqa/BT` (`MultiSubnetFailover`), PROD `wondersqlpd/BT`. ScadaBridge's 2026-06-16 design says the DEV BTDB is on **`wonder-sql-vd03/BT`** (db-connection id 1). `mes-delmia-integration-api.md` also says `vd01`. **Host drift is unresolved** — do not assume either without probing.
## 5. How BTDB relates to the rest of the family
```
Galaxy machine objects ──(script: EXEC StartMachineBatch / StartMachineCycle /
($Reactor_Side etc.) AddMachineBatchWorkOrder / AddOtherData* …)──────────┐
▼
Camstar MES ──HTTPS──▶ MESAPI/WWSupport ──(SELECT Machine by SAPID; alarm catalog; ┌────────────────────┐
(ServiceStack, own UserAuth/ApiKey tables) ────────────────▶ │ SQL Server "BT" │
│ (BTDB) │
ScadaBridge inbound API ──(Database helper, connection "BTDB": SELECT Code FROM │ co-tenant with │
(IpsenMESMoveIn, MES alarm-status) ─────────────────────────────────────────────▶ │ Historian Runtime │
ScadaBridge site scripts ──(Database.Connection / CachedWrite — customer scripts)─▶ │ + INSQL linked │
└─────────┬──────────┘
BTDBManager (config, batch edits, env import) ─────────────────────────────────────▶ │ CLR: OPENQUERY(INSQL) WideHistory,
SSRS / QlikView / Telerik reports ──(EXEC *_Wrapper, GetMachineBatchTSV …)──────────▶ │ Runtime.dbo.{TagExtendedPropertyInfo,
▼ DiscreteHistory, Events}
AVEVA Historian (Runtime DB)
```
- **Galaxy → BT** is the primary write path (batches/cycles/work orders/OtherData JSON). DARS `model_info.md` §: "Existing per-machine BT sprocs (`StartMachineBatch`, `StartMachineCycle`, `GetCycleTSV`, `Alarm_Wrapper`, …) work unchanged" — the sprocs are the contract Galaxy scripts bind to.
- **ScadaBridge → BT (verified):** the inbound-API script context has a `Database` helper bound to named db-connections; production defines connection **`BTDB`** (id 1), and the `IpsenMESMoveIn` (design 2026-06-16) and MES alarm-status (2026-06-30) methods do `SELECT Code FROM dbo.Machine WHERE SAPID=@s` before `Route.To(instance)`. Template/site scripts expose `Database.Connection(name)` + `Database.CachedWrite(...)`, so site scripts **can** write batches into BT — but **no checked-in ScadaBridge script calls a BT sproc**; any batch logging is customer-site script configuration, not platform code, and the docker rig does **not** seed a `BT` database (`infra/mssql/setup.sql` creates only `ScadaBridgeConfig` + `ScadaBridgeMachineData`; the `InboundDatabaseHelperTests` use a stand-in). ScadaBridge's inbound API is the designated successor of MESAPI's move-in/move-out surface, which is why it needs the same `SAPID → Code` lookup.
- **HistorianGateway ↔ BT:** no direct coupling, but both read `Runtime.dbo.Events` (HG's SQL-path `ReadEvents`) and both need the Historian SQL instance. BT's CLR `GetTSV`/`GetAggregateValues` is a bespoke, in-database equivalent of what HG's `ReadRaw`/aggregate retrieval modes do over gRPC — a candidate for consolidation if the report layer is ever re-platformed.
- **OtOpcUa / mxaccessgw:** no coupling.
- **Break surface:** the sproc signatures + `Machine.Code`/`SAPID`/`ZTag` semantics (Galaxy scripts, MESAPI, ScadaBridge inbound methods all bind to them), the `OtherData` JSON key conventions (DARS sprint 1 defines ~14 new keys with single writers), and the `INSQL`/`Runtime` co-location assumption.
## 6. Analysis — gaps and recommendations (2026-09-03)
1. **Push the branch.** ~~Put both copies under git~~ — done locally 2026-09-03 (`feat/machine-batch-transfer`). Remaining: push it to `ZimmerBiomet/BTDB`, review/merge, decide whether BTDB also gets a mirror on `gitea.dohertylan.com` like the other sisters, then delete the superseded `DARS/WW_ARCH/BatchTracker_DB/` copy.
2. **Rotate and externalize the checked-in credentials** (three SQL passwords, one domain account). _Externalised on `feat/manager-blazor` (`${secret:btdb/...}` refs, store outside the content root); rotation is a cut-over step (§8)._ The family standard is `ZB.MOM.WW.Secrets` `${secret:}` with an absolute `Secrets:SqlitePath` outside the content root.
3. **Manager re-platform** — _done on `feat/manager-blazor`, see §8_: net6.0 is EOL; Telerik is pinned by an absolute machine path; `System.DirectoryServices` binds the user's own credentials on a domain-joined box. A .NET 10 rewrite on the family libs is mostly assembly: Auth 0.3.0 (LDAP + `UG_WW_*` group→role mapping, `FallbackServers`), Theme 0.4.1, Health 0.3.0 (`MapZbHealth`, so Overview can watch it), Telemetry, Configuration, Audit (the batch-edit audit is a natural `ZB.MOM.WW.Audit` writer), Secrets. Keep Dapper + the embedded queries; replace Telerik `.trdp` with server-side rendering only if the three audit reports are still used.
4. **Injection surfaces in the SQL layer:** `AddOtherData*` build dynamic SQL from `@DataKey`/`@DataValue`; `GetTSV`/`GetAggregateValues` interpolate tag names and append `@queryParams` raw into `OPENQUERY`. Trusted callers today, but ScadaBridge scripts and the inbound API widen the caller set. Fix `AddOtherData*` with parameterised `JSON_MODIFY` (no dynamic SQL needed), and whitelist `queryParams` to the three `ww*` keys.
5. **ServiceStack auth tables** (`UserAuth*`, `ApiKey`) are MESAPI's, not BT's domain. Once ScadaBridge's inbound API fully replaces MESAPI (Ipsen MoveIn is the first slice; ScadaBridge keys already live in the `zbauth` schema via `Auth.ApiKeys.SqlServer` 0.3.0), those tables are dead weight in the schema and should be dropped from the sqlproj rather than carried forward.
6. **Host inventory drift:** 2023 config says DEV BT is on `wonder-sql-vd01`; ScadaBridge's 2026 design says `wonder-sql-vd03`. Probe and record the answer in `deployment.md` §2.1 (which currently has no BT row at all).
7. **`install.bat`/`uninstall.bat` are wrong for this project** (they install `WWNotificationSystem`). _Deleted on `feat/manager-blazor`; replaced by `deploy/install-service.bat` (NSSM, service `ZB.MOM.WW.BTDB.Manager`)._
8. **CLR + Historian co-location is a hard deployment constraint** the index did not previously record: BT cannot be moved to the app-tier SQL (`wonder-app-vd03,1433`, where ScadaBridge's ConfigDb lives) without breaking every report wrapper. Any consolidation plan must keep BT on the Historian instance or replace the CLR with HistorianGateway calls.
## 7. Primary commands (Windows only)
```powershell
# from ~/Desktop/btdb (master)
dotnet build Manager\BTDBManager.csproj # net6.0; needs Telerik Reporting R2 2022 at the HintPath
msbuild Database\Database.sqlproj /p:Configuration=Release # SSDT (VS 2022 + SSDT) → bin\Release\Database.dacpac
SqlPackage /Action:Publish /SourceFile:Database\bin\Release\Database.dacpac /TargetServerName:<historian-sql> /TargetDatabaseName:BT
# Instance prerequisites: CLR enabled, `INSQL` linked server, `Runtime` DB reachable by three-part name
```
```bash
# feat/manager-blazor (any OS for the app; SSDT still Windows-only)
./build.sh # restore + build (Release, warnings-as-errors) + test BTDB.slnx
dotnet run --project src/ZB.MOM.WW.BTDB.Manager # appsettings.Development.json → local glauth; needs a BT
pwsh deploy/publish.ps1 # self-contained win-x64 → deploy/out/ (+ NSSM install scripts)
```
```bash
# Local Docker rig (2026-09-04, any OS) — see §9
docker/deploy-db.sh # BT on scadabridge-mssql from Database/ (dacpac + SQL CLR); --recreate drops it first
docker/deploy.sh # publish FDD on the host → zb-btdb-manager:local, up on :9877 (glauth login enabled)
```
On `master` nothing builds on macOS (SSDT/CLR need Windows MSBuild, the MVC Manager needs Telerik + `System.DirectoryServices`). On the branch the app and its tests build and run on macOS; only `Database.sqlproj` (kept alone in `BTDB.sln`) still needs Windows — but §9's side projects build the same sources into a dacpac and a CLR assembly anywhere, for the local rig.
## 8. Blazor conversion — branch `feat/manager-blazor` (2026-09-04)
Plan: `btdb/docs/plans/manager_blazor_conversion.md` (+ `.tasks.json` tracker beside it; mockups `docs/mockups/manager_blazor_mockups.html`). Executed 2026-09-04 in worktree `~/.config/superpowers/worktrees/BTDB/feat-manager-blazor`; **uncommitted and unpushed at the time of writing** — phases 1–3 (scaffold, core, auth, widgets, queries, all pages) plus the local half of phase 4 are done; the DEV-box half of phase 4 (parity run, secrets seed + rotation, NSSM side-by-side, port swap) is written up as a runbook and not yet performed.
- **Shape on the branch:** `BTDB.slnx` = `src/ZB.MOM.WW.BTDB.Manager` (Blazor Web App, InteractiveServer, net10.0) + `src/ZB.MOM.WW.BTDB.Manager.Core` (Dapper data layer moved verbatim from the MVC app, hardened) + two xunit/bUnit test projects (334 tests, warnings-as-errors gate via root `Directory.Build.props`, `build.sh`/`build.ps1`). `BTDB.sln` keeps only `Database.sqlproj`. `Manager/` (MVC, Kendo, the three Telerik `.trdp` reports with embedded connection strings, the mis-named `install.bat`) is **deleted**; `/Api/GetMachines`+`GetMachineGroups` are gone (no external consumer — ScadaBridge/MESAPI read `dbo.Machine` by SQL).
- **Family libs:** Theme 0.4.1, Health 0.3.0 (`MapZbHealth`; readiness = a `SELECT 1` against `BT` with a 3 s timeout, so `/health/ready` is 503 until the DB answers — register it in Overview), Telemetry + Serilog 0.1.0, Configuration 0.1.0 (`ConfigPreflight` requires `ConnectionStrings:BT` and `Btdb:Security:Ldap:Server`), Secrets 0.6.2 (`${secret:btdb/connectionstrings/{bt,qa,prod}}`, `${secret:btdb/ldap/serviceaccountpassword}`; SQLite store `C:\ProgramData\ZB.MOM.WW\btdb-manager\secrets.db`, KEK from `ZB_SECRETS_MASTER_KEY`), Auth.Ldap/AspNetCore 0.3.0 (service-account bind, `Btdb:Security:GroupToRole` → `CanonicalRole`; policies Viewer / BatchEdit (Operator+) / MachineConfig (Administrator); cookie `btdb.auth`, plain-HTTP cookie because the box has no certificate). `Microsoft.Data.SqlClient` 7.x with `Encrypt=False` forced by `BtConnectionStrings.Normalize` unless the string sets it.
- **Behavioural deltas vs the MVC app worth knowing:** config import derives the group set from the selected machines' memberships (no separate group pick) and has a dry-run preview (`MachineConfigImportPreview.sql`: same MERGEs, `OUTPUT` into a table variable, always `ROLLBACK`); batch-edit timestamps are 7-fraction UTC strings validated on blur (no Kendo mask); the three audit reports are HTML tables with a print stylesheet instead of Telerik PDFs; `MachineAlarm` DTO property order/types were wrong in the MVC app (alarm import always threw) and are fixed against `MachineAlarmType`; every `Save*` runs in a transaction and `THROW 5001x` maps to `BtdbSaveException`.
- **Cut-over material:** `docs/operations/cut-over.md` (parity checklist per route + THROW paths + audit-username check, secrets seed via the `secret` console + rotation, NSSM side-by-side on `:9877`, port swap to `:9876`, Overview registry entry), `deploy/` (`publish.ps1`, `install-service.bat` / `uninstall-service.bat` for NSSM service `ZB.MOM.WW.BTDB.Manager`), `tools/smoke-new-queries.sql` (runs the six never-executed queries read-only against DEV with sqlcmd). Still open after cut-over: Overview lacks the mockup's per-machine "open > 24 h" rows; Ldap `Server`/`SearchBase`/`ServiceAccountDn` are blank in `appsettings.json` by design (per-environment).
## 9. Local Docker rig — `docker/` (2026-09-04)
Mirrors the HistorianGateway / Overview pattern: publish framework-dependent on the host (Gitea feed creds), copy into `aspnet:10.0`, never restore in Docker. Compose project `zb-btdb`, container `zb-btdb-manager`, image `zb-btdb-manager:local`, port `:9877` (same as the DEV side-by-side port, so `appsettings.json`'s Kestrel section is the single binding authority; the Dockerfile clears `ASPNETCORE_URLS`/`ASPNETCORE_HTTP_PORTS`). `ASPNETCORE_ENVIRONMENT=Production`; all environment-specific values are compose env vars, dev-only and committed under the family's rig exception.
- **Database:** no MSSQL of its own — joins the external `scadabridge-net` and uses ScadaBridge's `scadabridge-mssql` (the instance that already carries `ScadaBridgeConfig` + `ZbSecretsHub`). `docker/deploy-db.sh`: (1) `docker/db/BT.Clr.csproj` compiles `Database/**/*.cs` to `Database.dll` (net472 via the auto-referenced reference assemblies — builds on macOS); (2) `docker/db/BT.Local.sqlproj` (SDK-style `Microsoft.Build.Sql/2.2.0`, `EnableDefaultSqlItems=false`, globs the four `Database/` folders, Sql130 model, suppresses the legacy build's own SQL71562/71558/71502) → `BT.Local.dacpac`; (3) `db/setup.sql` — `BT` + login `btdb_app` (db_owner); (4) `db/clr-objects.sql` — `clr enabled` on the instance, `sp_add_trusted_assembly` by SHA2-512 (strict security stays on), `CREATE ASSEMBLY [Database] … SAFE` from the bytes streamed as 2000-char `0x` chunks (a single 57 KB literal gets split by sqlcmd), then `StringJoin` aggregate, `StringCompare`/`CheckTriggered`/`WhenTriggered`/`WhenCleared`/`GetAggregateValues`, `GetTSV`/`GetMachineBatchTSV`/`GetCycleTSV`/`GetLinkedBatchTSV` with SSDT's type mapping; (5) `sqlpackage /Action:Publish` from a one-shot container (`db/Dockerfile.sqlpackage`, SDK image + the dotnet tool — the host's 10.0.5 runtime could not run the tool's 10.0.11 pin) with `DropObjectsNotInSource=false`, `BlockOnPossibleDataLoss=false`, `AllowIncompatiblePlatform=true`; (6) smoke. Result on the rig: 23 tables, 37 T-SQL procs + 1 TVF, 10 CLR objects, `Database` assembly `SAFE_ACCESS`. The script diffs the legacy `<Build Include>` list against the folders and warns on drift (found: `ElmaData_Nitric.sql` + `Elma_Bulk_Query_Nitric.sql` were on disk but not in `Database.sqlproj` — added). `ScadaBridge/infra/teardown.sh`/`reseed.sh` drop the volume and BT with it; re-run `deploy-db.sh`.
- **Why not convert `Database.sqlproj` itself:** `Microsoft.Build.Sql` does not compile SQL CLR, and the Manager depends on `dbo.StringJoin` (batch search) and `dbo.StringCompare` (machine saves). The legacy SSDT project stays the artifact of record; the two side projects reference the same files, nothing is copied.
- **Login:** enabled, `host.docker.internal:3893` + `FallbackServers` `:3894` (glauth-redundant), bind `cn=serviceaccount,dc=zb,dc=local`; `GroupToRole` `SCADA-Admins→Administrator`, `SCADA-Designers→Operator`, `SCADA-Viewers→Viewer`. Verified: `admin`/`designer` sign in, `gw-viewer` refused (fail closed). Literal `ConnectionStrings__BT` / LDAP password env vars override the `${secret:}` refs, so the `/data/btdb-secrets.db` store stays empty and no master key is set (confirmed to boot without one). The two config-import sources point at the local BT.
- **Health / Overview:** `/healthz` 200, `/health/ready` 200 with the `sql` entry (503 when BT is down), `/health/active` 200, `/metrics`. Compose `healthcheck` = bash `/dev/tcp` GET of `/healthz` (liveness on purpose). Registered in `ZB.MOM.WW.Overview/src/…/appsettings.Docker.json` as application **BTDB Manager**, instance `manager`, `BaseUrl http://zb-btdb-manager:9877`, `HasActiveRole false`; the containerised Overview was republished and shows the tile Up with `sql` healthy (the dashboard already sits on `scadabridge-net`, so no extra network).
## 10. State as of 2026-09-11 (supersedes §1, §4, §6.1, §6.3, §6.7, §8 where they differ)
- **Everything is on local `master`** (`78195b8`): the Blazor conversion (§8) was merged, the
`feat/manager-blazor` worktree is gone, and the 2026-09-04 full review
(`docs/reviews/2026-09-04-full-review.md`, reviewed at `c624d41`) was remediated in 12 work-package
branches — `fix/save-batch-edit-null-compare`, `fix/db-lifecycle-sprocs`, `fix/clr-openquery-escaping`,
`fix/config-import-parents-and-nulls`, `test/db-integration`, `fix/manager-robustness`,
`fix/auth-hardening`, `ops/runbook-and-deploy`, `perf/indexes`, `db/schema-hygiene`,
`fix/concurrency-and-async`, `chore/nits` — all merged; 60 findings fixed, 3 partial by decision
(DB-15 `QV_*` impersonation, DB-16 alarm-CTE consolidation, DB-21 ServiceStack table drop), 0 open.
`feat/machine-batch-transfer` (DARS sprint 1, §1 item 1) is merged too, and so is
`feat/transfer-machine-batch` (merged `be976a6`, 2026-09-11): **`dbo.TransferMachineBatch`**, a tenth
Galaxy-facing writer that ends the source batch if still open, starts the destination batch by machine
`Code`, copies the `MachineBatchWO` rows still on the source (`MoveOutTimestamp IS NULL`, narrowed to
`@ContainerID`; blank = whole batch; source rows never modified) and records the `MachineBatchTransfer`
link — by composing `EndMachineBatch` / `StartMachineBatch` / `AddMachineBatchTransfer` in one owned
transaction. Outputs `@o_DestMachineBatchID`, `@o_MachineBatchTransferID`. Documented in
`docs/BatchTracker_Reference.md`; proven by `ValidateLifecycleSprocs.sql` §F (82 PASS on the rig).
`fix/transfer-lot-walk` (merged `5f0da01`, 2026-09-11) **reopened review DB-6**: the 2026-09-04 loop guard
in `AddMachineBatchTransfer` walked backward (toward the batches that fed the destination), which the
already-transferred check makes unreachable for any source, so `A→B` then `B→A` was still accepted; it
now walks forward along source→dest links with `HOLDLOCK`, and the destination row is held like the
source. The chain walks in `GetLinkedBatchTSV.cs` and `LinkedBatchAlarm_Wrapper.sql` picked one root
with `TOP 1` and dropped the other branch of a lot merge (`A→C, B→C`); both now resolve the whole lot
(forward to the final batch, then every batch that fed it) with one CTE pair pinned equal by
`SchemaHygieneTests`. Rig proofs: `ValidateLifecycleSprocs.sql` 87/0, `docker/db/validate-clr.sql`
27/0 over a merged lot with a `Runtime.dbo.Events` stand-in.
`feat/manager-transfers` (merged `695192d`, 2026-09-11) gave the **Manager** the transfer side it lacked: the
batch edit page edits the batch's outgoing `MachineBatchTransfer` row as a fourth MERGEd collection in
`SaveBatchEdit.sql` (guards `50015` self, `50016` destination missing, `50017` loop, `50018` more than one;
destination row and chain walk held like `AddMachineBatchTransfer`), audited into the new
`AuditLogMachineBatchTransfer` under the batch-edit header (new TVP `MachineBatchTransferType`); a read-only
lot panel (`GetBatchLot.sql`, the same `Down`/`Lot` CTE as the CLR, pinned equal by a static test); a lineage
column on Find Batch; a Transfers section on the batch-edit audit page and PDF. Rig proofs: 28 integration
tests (three new: round trip with audit, loop refused, merged lot), smoke 17/17, lifecycle 87/0, transfer
chains 4/0, validate-clr 27/0; gate 961 tests, 0 warnings. No branch is in flight.
- **`master` is ~198 commits ahead of `origin/master` (`d147c10`) and unpushed.** Pushing is the user's
call — the remote is the corporate `ZimmerBiomet/BTDB`.
- **Solution shape now:** `BTDB.slnx` = `src/ZB.MOM.WW.BTDB.Manager` (Blazor host) +
`src/ZB.MOM.WW.BTDB.Manager.Core` (Dapper data layer, embedded `Queries/*.sql`) + five test projects
(`Manager.Core.Tests` static query invariants, `Manager.Tests` bUnit/boot, `Database.Tests` static SQL
+ sqlproj invariants, `Clr.Tests` compiles the CLR sources into net10, `Manager.Core.IntegrationTests`
opt-in on the rig behind `BTDB_TEST_CONNECTION`). `BTDB.sln` keeps `Database/Database.sqlproj`
(Windows MSBuild only). `.gitea/workflows/build.yml` runs `./build.sh` (needs `GITEA_NUGET_TOKEN`).
- **Invariants a future session must not break** (all test-enforced): TVPs bind by ordinal so model
property order + lengths must equal `Database/Types/*.sql`; every write query is transaction-free and
audited (the C# wrapper owns the transaction); `dbo.X` only, never `BT.dbo.X`; `SYSUTCDATETIME()` in
Manager queries; every writer sproc follows the own-or-join `TRY/CATCH` template with locked lookups;
every `.sql` on disk must be in `Database.sqlproj`'s `<Build Include>` list; optimistic concurrency via
`ExpectedLastUpdate` → `THROW 50014`.
- **Secrets/credentials (§6.2):** `${secret:btdb/connectionstrings/{bt,qa,prod}}` (the LDAP
service-account secret is gone since 2026-10-01 — see below; only `dotnet run` against local glauth uses it), store at `C:\ProgramData\ZB.MOM.WW\btdb-manager\secrets.db`,
master key only in `ZB_SECRETS_MASTER_KEY`. Rotation is cut-over step 4.2.
- **Claude artifacts are gitignored + untracked in btdb** (2026-09-11): `CLAUDE.md`, `.claude/`,
`docs/plans/`, `docs/reviews/`, `*.tasks.json` — they exist on disk (btdb's `CLAUDE.md` is the repo
orientation and still loads) but never reach the corporate remote. `docs/operations/`,
`docs/BatchTracker_Reference.md`, `docs/mockups/` stay tracked.
- **Open step:** phase-4 cut-over on the DEV box (`docs/operations/cut-over.md`; 4.1 parity walk-through
gates the rest) — **blocked by the 2026-09-11 remote-access hold** (no psbridge, no winrm; UNC copies and
direct SQL logins still allowed). §6 item 6 (which SQL host carries DEV `BT`) is still unrecorded.
- **2026-10-01 — LDAP sign-in by user bind** (merged `a81a480`): Auth 0.4.0/0.4.1 added opt-in
`LdapOptions.BindMode=User`; BTDB ships it. Sign-in binds as `UserBindTemplate` (`<DOMAIN>\{0}` —
down-level maps exactly to the sAMAccountName the group search uses), the same connection reads the
user's own `memberOf`/`displayName`, and the username returned is the directory's spelling. No service
account, no LDAP secret; the preflight requires the template and refuses `AllowInsecure`/`Transport=None`
with user bind outside Development. Local dev + docker rig stay `BindMode=ServiceAccount` (GLAuth bind DNs
embed the user's OU). Rollout to the three Manager nodes (vd03 first) and retiring the stored secret are
the open steps (plan `docs/plans/2026-10-01-ldap-user-bind.md`, gitignored).
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -0,0 +1,36 @@
# ScadaBridge — index history
- **2026-10-13 existing fixes verified and issues closed.** Main `513fa1aa` already includes #35 fail-closed unavailable configured body/SQL redactors (`006202f3`) and #37 Flow Debugger structured/raw validated method inputs (`b5eb08f1`). Fresh full AuditLog project 407 passed/0 failed; FlowDebuggerPageTests 47 passed/0 failed; both terminal exit0. Remote ancestry confirmed; #35/#37 closed with evidence. No source changes/deployment/MES transactions. #36 runtime reset-echo overload is implemented, but QA/prod script port remains tracked; #30 per-site PSK deployment gate remains open.
- **2026-10-13 #36 runtime regression proof refreshed.** Rebuilt HandshakeResetEchoTests passed all three cases with local fakes, terminal exit0; an earlier no-build attempt matched no tests and is excluded from evidence. Tracker now distinguishes implemented runtime b623fdb0 from remaining QA/prod database-owned script rollout (deployment register row119, scripts13/14/36 and15/16/25/26/37/38). No database writes, deployments or fresh live rig claims.
- **2026-11-13 deployed `8e32f353` to wonder-app-vd03 (DEV) and enabled the audit hash chain** (was `424db155`; owner go on #107). 37 commits, no migration (64). Build: clean worktree, self-contained win-x64, zip SHA-256 `0cf06cf5…7fdebc`, LocalDb 0.3.8. WinRM swap 07:13–07:14 EST, site data path ~45 s, central API ~25 s; `sc failureflag 1` on both services (restart actions existed, but non-crash failures were FALSE, so a #132 exit 75 would have left the node stopped). Env block digest-identical before/after. **#131 applied** (`apply.sh apply 131`, SBTEST01/02 deployments 95/96; verify groups C+D 13/13 on the old binary and again after; C13 skipped because SAPID 103559 routes to Z28061) — #131 closed. Gates: health 200 ×4, MxGateway Connected 398/412 = baseline, Z28062 144 Good = baseline, AuditLog writing, Overview Up. **Hash chain:** backfill 843 → `unknown`, then `AuditLog__HashChain__Enabled=true` in the Central service env (ChainBacklog unset, head export off, single login), Central-only restart; one anchor (2026-11 `ChainSeq 0`, cutoff 2026-11-13T12:16:53.114Z), 0 pre-cutoff rows chained, `verify-chain 2026-11` Intact with 507 pre-cutoff rows, 2026-10 NotChained (667). Backup `ScadaBridge_pre-8e32f353_20261113T071302.bak`; rollback scripts in `E:\ApiInstall\_stage-sb-8e32f353\`. Record `docs/deployment/deployment-records/2026-11-13-wonder-app-vd03-8e32f353.md` (`581e25ca`). QA not deployed.
- **2026-11-11 deployed `424db155` to wonder-app-vd03 (DEV)** (was `0e540291`). Owner-approved WinRM deploy. Migrations 58→64 (`AddNativeAlarmSourceMesReportable`, `PrefixSearchIndexes`, `AddAuditLogHashChain`, `AddConfigGraphRowVersions`, `FlipAuditLogClusteredKey`, `AuditMaintenanceGrants`) applied by script with central + site stopped; #111 DEV sizing: 2,394 rows / 8 MB flip in ~1.5 s. **The plain `dotnet ef migrations script --idempotent` output fails (Msg 207 `ChainSeq`: column added and indexed in one batch)** — the deployed script adds `GO` per guarded block + `XACT_ABORT`; forward/rollback rehearsed on a restored copy of the vd03 DB. Downtime ~50 s; verify OK. Backup `ScadaBridge-backups\ScadaBridge_pre-424db155_20261111T164219.bak`. QA not deployed.
- **2026-11-12 #129 alarm Severity runs one direction (higher = more urgent), main `dd4f1c2a`.** MxGateway native alarms and computed `PriorityLevel` now band AVEVA-style priority onto `AlarmConditionState.Severity` with OtOpcUa's `GalaxyAlarmPriority` table (lmxopcua#887): 1–250→1000, 251–500→750, 501–750→500, 751–999→250, ≤0→1000, >999→250 (`AlarmPriorityBands`). OPC UA rows are unchanged. The raw number (= pre-#129 Severity) is kept on new `AlarmConditionState.Priority`, `ScriptAlarm.Priority` and `AlarmStateChanged.Priority`. There is no proto change: central derives Severity from the wire `priority` by kind, and pre-#129 `native_alarm_state` rows are upgraded on rehydrate. The native MES 900–999 band and the MES API `Severity`/`MinSeverity`/`MaxSeverity` key off `Priority`, so they select the same alarms as before. The rig seed scripts were switched; **deployed MES scripts (CvdReactor, vd03 SBTEST01/02) must switch `a.Severity`→`a.Priority` in the same deploy: deploy gate ScadaBridge#131.** **Visible flip:** Alarm Summary worst/filter/sort and the Sev column now rank AVEVA priority 1 highest. A computed raise logs `Error` at priority 1–500 (was raw ≥700). Tests (Release): Commons 977, DCL 549, Communication 834, SiteRuntime 1055, CentralUI 1545, all green; a mutation revert turned 62 red. Not deployed.
- **2026-11-12 OPC Foundation SDK 1.5.378.106 → 1.5.378.182 (`main` `e36cd605`, ScadaBridge#125 ask 2, owner option B; not deployed).**
- Client (DCL) and the test-only Server move in lockstep. No source changes, no API breaks.
- Release build has 0 warnings. DCL tests pass 536/536.
- **Wire-compat re-run** with the bumped client, using the lmxopcua harness (`438484fd`, run at master `2e9cccbd`), ACL off:
- The matrix passes 11/11 in None, Sign and SignAndEncrypt, against both the SDK 1.5 baseline `83ed880e` and the SDK **2.0.1** master `a28adba2`.
- All 8 trust controls fail closed (0x80130000 and 0x801A0000).
- Failover passes 8/8 legs, with the same timings as on the old client.
- **Operational note:** since .156, a CA-issued OPC UA server cert that the DCL trusts needs an issuer with `keyCertSign`. SDK self-signed certs are unaffected.
- **2.0.x is deferred** until lmxopcua#799 and #801 close. #125 stays open to track it.
- **2026-11-12 OPC Foundation SDK 1.5.378.182 → 2.0.1 (`main` `a2e9d718`, ScadaBridge#125 closed; not deployed).** Done once lmxopcua#782/#799/#801 had closed. Client (DCL) and the test-only Server move in lockstep; the transitive Core/Core.Types/Types/Configuration/Security.Certificates packages resolve to 2.0.1.
- **API breaks fixed (DCL only):**
- Immutable `Variant`/`DataValue`/`NodeId`/`StatusCode` and `ArrayOf<T>`. New `OpcUaValueBoundary` restores the SDK 1.5 CLR value shapes (`byte[]`, UTC `DateTime` with no-timestamp = `MinValue`, `Guid`, detached arrays) and keeps `new Variant(object)` write semantics.
- `StatusCodes` are no longer constants, so code matches them by value.
- `CertificateIdentifier.Certificate` and the `CertificateValidation` event are gone. The SDK-created `CertificateManager` owns the identity and trust lists and is disposed with the session; auto-accept and the verify probe use `AcceptError`.
- X509 user identity now goes through `X509IdentityTokenHandler`.
- **UserName = `LegacyRsaUserNameIdentityTokenHandler`** (ported from OtOpcUa `be28aa44`, lmxopcua#880). SDK 2's default handler sends a 65-char API key as an `RsaEncryptedSecret`, which SDK 1.5 servers reject (`BadIdentityTokenInvalid`) and SDK 2 servers clock-gate (#873). The DCL sends what it sent on 1.5, so it works against both server generations in a mixed rollout.
- **Operational:** SDK 2 never accepts an incomplete chain or an empty subject/issuer DN, even with `AutoAcceptUntrustedCerts`. The `keyCertSign` rule from .156 still applies.
- **Tests:** Release 0 warnings; DCL 570/570 incl. the #121 secure-connect tests and opc-plc live tests. The new handler tests are mutation-checked. Whole solution 11,345 passed / 188 failed (185 Playwright with no browser server, 3 load flakes that pass in isolation).
- **Wire-compat re-run:** lmxopcua harness, its key now the 65-char production shape (`2705f166`). Against baseline `83ed880e` (SDK 1.5) and master `412da27c` (SDK 2.0.1):
- Matrix 11/11 ×3 modes on both servers, ACL off and on; 8 trust controls fail closed.
- Failover 8/8. Kill reaches the backup in about 20 s as before; freeze is detected in about 15 s (was about 20 s).
- A mutation run with the SDK default UserName handler fails every SDK 1.5 leg with `BadIdentityTokenInvalid`, which is #880 reproduced from the consumer side.
- Evidence: `~/validation-evidence/scadabridge-125/client-2.0.1/` (contains private PKI; not committed).
+4 -2
View File
@@ -7,8 +7,10 @@ obj/
[Aa]rtifacts/
*.user
# Claude Code tooling / agent worktrees (local-only)
.claude/
# Claude Code tooling / agent worktrees (local-only) — but .claude/skills/ IS tracked:
# the sister-project-history skill holds the per-project narratives the root index points at.
.claude/*
!.claude/skills/
# Local ops/infra notes — internal access details, never publish
zimmer-vpn-tunnel.md
+132 -172
View File
File diff suppressed because one or more lines are too long
+82 -30
View File
@@ -15,12 +15,18 @@ it produces.
| Path | What it is |
|---|---|
| [`CLAUDE.md`](CLAUDE.md) | High-level index of the sister projects + working guidance |
| [`components/`](components/) | Component-normalization framework (per concern: target spec, current state, gaps) |
| [`components/auth/`](components/auth/) | First normalized component — login / identity / authorization |
| [`components/ui-theme/`](components/ui-theme/) | Second normalized component — UI theme / design tokens / layout |
| [`docs/plans/`](docs/plans/) | Implementation plans (e.g. the ZB.MOM.WW.Auth and ZB.MOM.WW.Theme builds) |
| [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/) | **Built shared library** (.NET 10) — the realized output of the auth normalization |
| [`ZB.MOM.WW.Theme/`](ZB.MOM.WW.Theme/) | **Built shared RCL** (.NET 10) — the realized output of the UI-theme normalization |
| [`components/`](components/) | Component-normalization framework (per concern: target spec, current state, gaps) — 7 components |
| [`docs/plans/`](docs/plans/) | Implementation + design plans (incl. Galaxy Repository and LocalDb, which have no `components/` entry) |
| [`infra/glauth/`](infra/glauth/) | The shared GLAuth every app's dev/test LDAP points at (`10.100.0.35:3893`) |
| [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/) | **Built shared library** (.NET 10) — login / identity / API keys |
| [`ZB.MOM.WW.Theme/`](ZB.MOM.WW.Theme/) | **Built shared RCL** (.NET 10) — Technical-Light design system |
| [`ZB.MOM.WW.Audit/`](ZB.MOM.WW.Audit/) | **Built shared library** — canonical audit event + writer seam |
| [`ZB.MOM.WW.Health/`](ZB.MOM.WW.Health/) | **Built shared library** — readiness / liveness / active-node probes |
| [`ZB.MOM.WW.Telemetry/`](ZB.MOM.WW.Telemetry/) | **Built shared library** — OTel metrics / traces + Serilog |
| [`ZB.MOM.WW.Configuration/`](ZB.MOM.WW.Configuration/) | **Built shared library** — options validation + startup preflight |
| [`ZB.MOM.WW.Secrets/`](ZB.MOM.WW.Secrets/) | **Built shared library** — AES-256-GCM secret store + `${secret:}` resolution + CLI + SQL-Server / Akka cluster replication |
| [`ZB.MOM.WW.GalaxyRepository/`](ZB.MOM.WW.GalaxyRepository/) | **Built shared library** — Galaxy object-hierarchy SQL browse + gRPC service |
| [`ZB.MOM.WW.LocalDb/`](ZB.MOM.WW.LocalDb/) | **Built shared library** — embedded SQLite cache + 2-node gRPC replication |
## The sister projects
@@ -33,6 +39,8 @@ not by a shared build. scadaproj *indexes* them; it does not contain them.
MXAccess parity without loading 32-bit COM. The linchpin both others depend on.
- **ScadaBridge** — distributed SCADA platform on Akka.NET (hub-and-spoke: one central cluster
+ N site clusters); its Data Connection Layer ingests OPC UA and MxAccess.
- **HistorianGateway** (`historiangw`) — gRPC sidecar over the AVEVA Historian (read/write) plus
read-only Galaxy browse; no COM, no x86 worker. OtOpcUa's sole historian backend.
Data flow:
@@ -51,17 +59,27 @@ The sister repos kept re-implementing the same cross-cutting concerns and drifti
**code-verified current state**, and a **gaps / adoption backlog**. Convention + workflow in
[`components/README.md`](components/README.md).
| Component | Status | Folder |
|---|---|---|
| Auth (login / identity / authz) | Built (library 0.1.0); apps not yet adopted | [`components/auth/`](components/auth/) |
| UI Theme (layout / tokens / components) | Built (RCL 0.1.0); apps not yet adopted | [`components/ui-theme/`](components/ui-theme/) |
Status verified 2026-07-18 against the feed + consumer branches (see [Roadmap](#roadmap)).
"All four" = OtOpcUa, MxAccessGateway, ScadaBridge, HistorianGateway.
| Component | Feed | Adoption | Folder |
|---|---|---|---|
| Auth (login / identity / authz) | `0.1.0`–`0.1.5` | mxaccessgw / ScadaBridge / HistorianGateway @ `0.1.5`; OtOpcUa @ `0.1.1` | [`components/auth/`](components/auth/) |
| UI Theme (layout / tokens / components) | `0.2.0`–`0.3.1` | all four @ `0.3.1` | [`components/ui-theme/`](components/ui-theme/) |
| Audit (event model + writer seam) | `0.1.0` | all four (DEEP) | [`components/audit/`](components/audit/) |
| Config + validation | `0.1.0` | all four | [`components/configuration/`](components/configuration/) |
| Observability (metrics / traces / logs) | `0.1.0` | all four | [`components/observability/`](components/observability/) |
| Health (readiness / liveness / active-node) | `0.1.0` | all four | [`components/health/`](components/health/) |
| Secrets (encrypted store + `${secret:}`) | `0.1.0`–`0.2.0` | all four @ `0.1.2` (`0.1.3`/`0.2.0` published, not yet consumed) | [`components/secrets/`](components/secrets/) |
| Galaxy Repository (SQL browse + gRPC) | `0.1.0`, `0.2.0` | HistorianGateway + mxaccessgw | _(design in `docs/plans/`)_ |
| LocalDb (embedded cache + 2-node sync) | `0.1.0` | none yet | _(design in `docs/plans/`)_ |
## `ZB.MOM.WW.Theme` — the shared UI kit
The UI-theme component, realized as a single-package .NET 10 Razor Class Library the three
apps can adopt to stop copy-pasting the Technical-Light design system. **Built and tested at
0.1.0; adoption by the apps is the follow-on** (tracked in
[`components/ui-theme/GAPS.md`](components/ui-theme/GAPS.md)).
The UI-theme component, realized as a single-package .NET 10 Razor Class Library that replaced
each app's copy-pasted Technical-Light design system. **Adopted by all four apps, currently on
`0.3.1`** (feed carries `0.2.0`–`0.3.1`); adoption history in
[`components/ui-theme/GAPS.md`](components/ui-theme/GAPS.md).
| Asset / Component | Purpose | Used by |
|---|---|---|
@@ -74,16 +92,16 @@ apps can adopt to stop copy-pasting the Technical-Light design system. **Built a
| `LoginCard` | Static form-POST sign-in card | OtOpcUa, ScadaBridge (MxGateway when login page added) |
| `TechButton`, `TechCard`, `TechField` | Common controls (Bootstrap 5 wrappers) | all |
**Consumer matrix:** all three apps consume the single `ZB.MOM.WW.Theme` package —
OtOpcUa `AdminUI`, MxAccessGateway `Server`, ScadaBridge `Host` + `CentralUI`.
**Consumer matrix:** all four apps consume the single `ZB.MOM.WW.Theme` package —
OtOpcUa `AdminUI`, MxAccessGateway `Server`, ScadaBridge `Host` + `CentralUI`, HistorianGateway `Server`.
### Build & test
```bash
cd ZB.MOM.WW.Theme
dotnet build -c Release # 0 warnings (TreatWarningsAsErrors)
dotnet test # 32 bUnit tests
./build/pack.sh # → ./artifacts/ZB.MOM.WW.Theme.0.1.0.nupkg
dotnet test # 48 bUnit tests (verified 2026-07-18)
./build/pack.sh # → ./artifacts/ZB.MOM.WW.Theme.<version>.nupkg (feed is at 0.3.1)
```
Stack: .NET 10 · Razor Class Library · bUnit · xUnit · central package management.
@@ -93,9 +111,10 @@ More detail: [`ZB.MOM.WW.Theme/README.md`](ZB.MOM.WW.Theme/README.md).
## `ZB.MOM.WW.Auth` — the shared library
The auth component, realized as a four-package .NET 10 library the three apps can adopt to stop
re-implementing authentication. **Built and tested at 0.1.0; adoption by the apps is the
follow-on** (tracked in [`components/auth/GAPS.md`](components/auth/GAPS.md)).
The auth component, realized as a four-package .NET 10 library that replaced each app's
re-implemented authentication. **Adopted by all four apps** — pins drift deliberately
(OtOpcUa `0.1.1`, ScadaBridge `0.1.3`, MxAccessGateway + HistorianGateway `0.1.4`); history in
[`components/auth/GAPS.md`](components/auth/GAPS.md).
| Package | Purpose | Used by |
|---|---|---|
@@ -105,7 +124,7 @@ follow-on** (tracked in [`components/auth/GAPS.md`](components/auth/GAPS.md)).
| `ZB.MOM.WW.Auth.AspNetCore` | Canonical claim types, cookie defaults, LDAP DI helpers | all (web UIs) |
**Consumer matrix:** OtOpcUa → `Abstractions + Ldap + AspNetCore` (no ApiKeys / SQLite);
MxAccessGateway & ScadaBridge → all four.
MxAccessGateway, ScadaBridge & HistorianGateway → all four packages.
Identity (LDAP / GLAuth, the canonical role set) is normalized; each app keeps its own
**authorization enforcement** (OPC-UA permissions / gRPC scopes / roles + site-scoping) and maps
@@ -117,8 +136,8 @@ and [`CANONICAL-ROLES.md`](components/auth/spec/CANONICAL-ROLES.md).
```bash
cd ZB.MOM.WW.Auth
dotnet build -c Release # 0 warnings
dotnet test # 172 passing, 1 skipped (opt-in LDAP integration test)
dotnet pack -c Release -o ./artifacts # → 4 nupkgs @ 0.1.0
dotnet test # 215 passing, 1 skipped (opt-in LDAP integration test) — verified 2026-07-18
dotnet pack -c Release -o ./artifacts # → 4 nupkgs (feed is at 0.1.4)
```
Stack: .NET 10 · xUnit · `Novell.Directory.Ldap.NETStandard` · `Microsoft.Data.Sqlite` · central
@@ -133,10 +152,43 @@ ZB_LDAP_IT=1 dotnet test # requires a reachable GLAuth (e.g. a sister repo's i
## Roadmap
- ✅ Auth component normalized (spec + canonical roles + current-state + gaps).
- ✅ `ZB.MOM.WW.Auth` shared library built and tested (0.1.0).
- ⬜ Adopt `ZB.MOM.WW.Auth` in OtOpcUa, MxAccessGateway, ScadaBridge — [`components/auth/GAPS.md`](components/auth/GAPS.md) (#8).
- ✅ UI-theme component normalized (spec + design tokens + current-state + gaps).
- ✅ `ZB.MOM.WW.Theme` shared UI kit built and tested (0.1.0); apps not yet adopted.
- ⬜ Adopt `ZB.MOM.WW.Theme` in OtOpcUa [low risk], ScadaBridge [med], MxAccessGateway [high risk] — [`components/ui-theme/GAPS.md`](components/ui-theme/GAPS.md).
> **Verified 2026-07-18** against the Gitea feed (`nuget/query?q=ZB.MOM.WW`) and the actual
> `PackageReference`s on each consumer's default branch — not from status claims in docs.
> Per-component detail in each `components/<name>/GAPS.md`.
**Shipped**
- ✅ Auth normalized + `ZB.MOM.WW.Auth` built (feed: `0.1.0`–`0.1.5`) and **adopted by all four apps**.
`0.1.5` (2026-07-18) pins patched SQLitePCLRaw; **mxaccessgw, ScadaBridge and HistorianGateway bumped to it**.
OtOpcUa stays at `0.1.1` — it takes no `ApiKeys`/SQLite dependency, so it was never exposed.
- ✅ UI Theme normalized + `ZB.MOM.WW.Theme` built (feed: `0.2.0`–`0.3.1`); **all four apps on `0.3.1`**.
- ✅ Audit — `ZB.MOM.WW.Audit` `0.1.0` on the feed; adopted by all four (DEEP: canonical record everywhere).
- ✅ Configuration — `ZB.MOM.WW.Configuration` `0.1.0` on the feed; adopted by all four.
- ✅ Observability — `ZB.MOM.WW.Telemetry` + `.Serilog` `0.1.0` on the feed; adopted by all four.
- ✅ Health — `ZB.MOM.WW.Health` (+ `.Akka`, `.EntityFrameworkCore`) `0.1.0` on the feed; **adopted by all four**
(`MapZbHealth` wired in each; previously documented as "not yet adopted" — that was stale).
- ✅ Galaxy Repository — `ZB.MOM.WW.GalaxyRepository` `0.2.0` on the feed; consumed by HistorianGateway
**and mxaccessgw** (which wires `AddZbGalaxyRepository` in its Server; previously documented as a
pending follow-on — also stale).
- ✅ Secrets — `ZB.MOM.WW.Secrets` (+ `.Abstractions`, `.Ui`) published through **`0.1.3`** (KEK rotation,
2026-07-18); all four apps still pinned at `0.1.2`.
- ✅ Secrets G-7 clustered replication — **built 2026-07-18 at `0.2.0`**, both fork options:
`ZB.MOM.WW.Secrets.Replicator.SqlServer` (shared store *and* local-plus-hub) and
`ZB.MOM.WW.Secrets.Replicator.AkkaDotNet` (peer-to-peer, partition-tolerant). Verified against a
real SQL Server 2022 and an in-process 2-node Akka cluster. **Published to the feed 2026-07-18**
(restore-verified).
- ✅ LocalDb — `ZB.MOM.WW.LocalDb` (+ `.Contracts`, `.Replication`) built at `0.1.0` and **published to the
feed 2026-07-18** (restore-verified from a scratch consumer).
**Open**
- ⬜ Adopt a clustered secrets topology in ScadaBridge / OtOpcUa — config + a shared KEK, no code
change. `0.2.0` is on the feed. [`components/secrets/GAPS.md`](components/secrets/GAPS.md).
- ⬜ Bump the four Secrets consumers `0.1.2` → `0.1.3`/`0.2.0` (KEK rotation + the same security fix).
- ⬜ Clear the pre-existing `AngleSharp` NU1902 build break in ScadaBridge `CentralUI.Tests`
and HistorianGateway `Tests` — both fail full-solution builds under `TreatWarningsAsErrors`.
- ⬜ Adopt `ZB.MOM.WW.LocalDb` in an app — no consumer references it yet.
- ⬜ Give LocalDb a `components/localdb/` entry; it is the one shared lib whose design lives only in
[`docs/plans/2026-07-17-localdb-design.md`](docs/plans/2026-07-17-localdb-design.md).
- ⬜ Converge the Auth version pins (OtOpcUa is three minors behind at `0.1.1`).
- ⬜ Normalize the next cross-cutting component.
+37
View File
@@ -0,0 +1,37 @@
# ZB.MOM.WW.Audit
Shared audit event model + writer seam for the **ZB.MOM.WW SCADA family** (single package; DEEP-adopted by all apps as the canonical record). Build/test from this directory: `dotnet test`. Component spec + gaps: `../components/audit/`.
## Index history (migrated from the scadaproj root CLAUDE.md)
> Moved verbatim out of the scadaproj root `CLAUDE.md` on 2026-09-03 so it loads only when needed. **This file is now the authoritative place for this history — append new entries here and keep the root index row short.**
### Narrative
The audit component is fully populated: a normalized [`spec`](components/audit/spec/SPEC.md), an
[`event-model`](components/audit/spec/EVENT-MODEL.md) reference, a
[`shared-contract`](components/audit/shared-contract/ZB.MOM.WW.Audit.md), three
[`current-state`](components/audit/current-state/) docs, and an adoption [`GAPS`](components/audit/GAPS.md)
backlog. Common ground = canonical `AuditEvent` record + `AuditOutcome` enum + `IAuditWriter` /
`IAuditRedactor` seams + helpers (`NullAuditRedactor`, `TruncatingAuditRedactor`, `NoOpAuditWriter`,
`CompositeAuditWriter`, `RedactingAuditWriter`) + `AddZbAudit` DI registration; left per-project =
transport/storage and domain vocabulary. Closes the loop on Auth — audit's `Actor` field = the Auth
principal. `IAuditRedactor` is aligned with Telemetry's `ILogRedactor` seam convention.
The shared library is **built and lives in this repo** at [`ZB.MOM.WW.Audit/`](ZB.MOM.WW.Audit/)
(.NET 10; 1 package — `ZB.MOM.WW.Audit`; only non-BCL dependency `Microsoft.Extensions.DependencyInjection.Abstractions`;
23 tests (verified 2026-07-18); `dotnet pack` → 1 nupkg @ 0.1.0). Repo: `https://gitea.dohertylan.com/dohertj2/zb-mom-ww-audit`.
**Adopted across all three apps on 2026-06-02** (audit GAPS #1–#6) on each repo's `feat/adopt-zb-audit` branch
(stacked on `feat/adopt-zb-auth`) — committed + reviewed, then **merged into the repo's local default (main/master)
and PUSHED to origin (gitea) on 2026-06-03** (in sync). Depth =
**DEEP adopt** (the canonical 9-field `AuditEvent` is the record everywhere; domain fields ride in `DetailsJson`).
OtOpcUa: canonical record + `AuditWriterActor : IAuditWriter` + `Outcome` column/migration + `ClusterAudit` fix.
MxGateway: new canonical SQLite `audit_event` store + `IAuditWriter` + `IApiKeyAuditStore`→canonical adapter.
**ScadaBridge: a full audit-subsystem re-architecture** (the program's largest task) — canonical record everywhere via a
deterministic codec; site SQLite split into `audit_event` + an `audit_forward_state` forwarding sidecar; central
partitioned `dbo.AuditLog` collapsed to 10 canonical cols + persisted computed cols (`CollapseAuditLogToCanonical`
migration, MSSQL-verified). Phase 3 wires `Actor` from the Auth principal at authenticated emit sites (per-app
`IAuditActorAccessor`). Per-repo detail in [`components/audit/GAPS.md`](components/audit/GAPS.md) +
`docs/plans/2026-06-02-auth-audit-normalization-phase2-deep.md` + `…-scadabridge-audit-rearch.md`.
Build/test from `ZB.MOM.WW.Audit/`: `dotnet test`. Consumer matrix: all three apps consume the single
`ZB.MOM.WW.Audit` package (OtOpcUa, MxAccessGateway, ScadaBridge — DEEP-adopted as the canonical record).
+12 -8
View File
@@ -16,11 +16,15 @@ Canonical audit event model, best-effort writer seam, and redactor seam for the
| Consumer | ZB.MOM.WW.Audit |
|---|:---:|
| **OtOpcUa** | yes (adoption deferred) |
| **MxAccessGateway** | yes (adoption deferred) |
| **ScadaBridge** | yes (adoption deferred — "align, don't replace") |
| **OtOpcUa** | yes — DEEP-adopted 2026-06-02 (canonical record + `AuditWriterActor : IAuditWriter`), pins `0.1.0` |
| **MxAccessGateway** | yes — DEEP-adopted 2026-06-02 (canonical SQLite `audit_event` store + `IAuditWriter`), pins `0.1.0` |
| **ScadaBridge** | yes — DEEP-adopted 2026-06-02 (audit-subsystem re-architecture onto the canonical record), pins `0.1.0` |
| **HistorianGateway** | yes — `AddZbAudit` + `IAuditWriter`, pins `0.1.0` |
Adoption is tracked in `components/audit/GAPS.md` in the outer `scadaproj` workspace. Each app brings its own transport (Akka broadcast / SQLite append / SQL ingest) and domain vocabulary (channels / kinds / event-types) — those stay per-project. The shared library provides the canonical record and the two seams that decouple "what to audit" from "how to store it".
All four apps pin `0.1.0` (the only version on the Gitea feed), verified against each repo's origin default
branch 2026-11-09. The 2026-06-02 adoption was merged and pushed on 2026-06-03.
Adoption history is in `components/audit/GAPS.md` in the outer `scadaproj` workspace. Each app brings its own transport (Akka broadcast / SQLite append / SQL ingest) and domain vocabulary (channels / kinds / event-types) — those stay per-project. The shared library provides the canonical record and the two seams that decouple "what to audit" from "how to store it".
---
@@ -53,7 +57,7 @@ dotnet test ZB.MOM.WW.Audit.slnx
Full design docs live in the `components/audit` folder of the SCADA project workspace:
- `~/Desktop/scadaproj-audit/components/audit/spec/SPEC.md` — overall audit specification
- `~/Desktop/scadaproj-audit/components/audit/spec/EVENT-MODEL.md` — field-by-field event model + per-project mapping table
- `~/Desktop/scadaproj-audit/components/audit/shared-contract/ZB.MOM.WW.Audit.md` — public API contract (on paper)
- `~/Desktop/scadaproj-audit/components/audit/GAPS.md` — adoption backlog
- `~/Desktop/scadaproj/components/audit/spec/SPEC.md` — overall audit specification
- `~/Desktop/scadaproj/components/audit/spec/EVENT-MODEL.md` — field-by-field event model + per-project mapping table
- `~/Desktop/scadaproj/components/audit/shared-contract/ZB.MOM.WW.Audit.md` — public API contract (on paper)
- `~/Desktop/scadaproj/components/audit/GAPS.md` — adoption backlog
+7 -1
View File
@@ -1,4 +1,10 @@
#!/usr/bin/env bash
# pack.sh — produce the ZB.MOM.WW.Audit NuGet package into ./artifacts.
set -euo pipefail
dotnet pack -c Release -o ./artifacts
# cd to the repo root and name the solution + an absolute output path: `dotnet pack` with
# neither a project argument nor a fixed working directory packs whatever solution happens
# to sit in the CALLER's directory (the bug behind the LocalDb feed incident, 0038d46).
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$REPO_ROOT"
dotnet pack ZB.MOM.WW.Audit.slnx -c Release -o "$REPO_ROOT/artifacts"
+13 -2
View File
@@ -16,9 +16,20 @@ set -euo pipefail
: "${GITEA_NUGET_SOURCE:?set GITEA_NUGET_SOURCE to your Gitea NuGet feed URL}"
: "${GITEA_NUGET_KEY:?set GITEA_NUGET_KEY to your Gitea access token}"
dotnet pack -c Release -o ./artifacts
# Named solution, named output, and a cd to the repo root, all for one reason: `dotnet pack`
# with neither a project argument nor a fixed working directory packs whatever solution
# happens to sit in the CALLER's directory — and then pushes it to a live feed under this
# script's name. Invoked by absolute path from another repo's checkout, the relative form
# packed and published 25 unrelated packages (LocalDb's copy of this script, fixed in
# 0038d46; recovered with `dotnet nuget delete`, but only because the token happened to
# carry delete rights). A publish script must be unambiguous about WHAT it publishes no
# matter where it is run.
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$REPO_ROOT"
dotnet nuget push "./artifacts/*.nupkg" \
dotnet pack ZB.MOM.WW.Audit.slnx -c Release -o "$REPO_ROOT/artifacts"
dotnet nuget push "$REPO_ROOT/artifacts/*.nupkg" \
--source "$GITEA_NUGET_SOURCE" \
--api-key "$GITEA_NUGET_KEY" \
--skip-duplicate
@@ -11,8 +11,8 @@
<PackageId>ZB.MOM.WW.Audit</PackageId>
<Authors>ZB.MOM.WW</Authors>
<Description>Canonical audit event model + best-effort writer and redactor seams for the ZB.MOM.WW SCADA family.</Description>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-audit</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-audit</RepositoryUrl>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/scadaproj/src/branch/main/ZB.MOM.WW.Audit</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/scadaproj</RepositoryUrl>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
+59
View File
@@ -0,0 +1,59 @@
# ZB.MOM.WW.Auth
Shared login / identity / API-key library for the **ZB.MOM.WW SCADA family** (4 packages + `ApiKeys.SqlServer`; consumed by OtOpcUa, ScadaBridge, MxAccessGateway, HistorianGateway). Build/test from this directory: `dotnet test` (the `ApiKeys.SqlServer` live suite is gated on `AUTH_SQLSERVER_CONNSTR`). Component spec + gaps: `../components/auth/`.
**Backlog / open work:** lives in Gitea issues on `dohertj2/scadaproj` (`tea issues list --repo dohertj2/scadaproj`) — currently #5 (roll apps to `0.4.1`), #6 (VD03 NAM AD cutover), #18 (Secrets migrator jitter, ported from here). The history below is a record, not a status tracker; file new follow-ups as issues.
## Index history (migrated from the scadaproj root CLAUDE.md)
> Moved verbatim out of the scadaproj root `CLAUDE.md` on 2026-09-03 so it loads only when needed. **This file is now the authoritative place for this history — append new entries here and keep the root index row short.**
### Component-table row as it read in the index
| Component | Status | Goal | Design | Implementation |
|---|---|---|---|---|
| Auth (login / identity / authz) | Adopted (**feed carries `0.3.0` as of 2026-09-02 — five packages, the new one being `ZB.MOM.WW.Auth.ApiKeys.SqlServer`; ALL FOUR apps pin `0.3.0` as of 2026-09-03**: OtOpcUa `master @ b8b4c18f`, ScadaBridge `main @ e45c4af9` (the `inbound-api-key-shared-store` work, merged), MxAccessGateway `main @ 4f931e4`, HistorianGateway `main @ d8d890c` — each built + tested with no new failures versus its pre-bump baseline, all PUSHED to origin. The preceding `0.2.1` pins landed 2026-08-13 (OtOpcUa `08e33fc7`, ScadaBridge `d28824d9`, MxAccessGateway `1cb14d2`, HistorianGateway `e42ff31`). **`0.2.0` (2026-08-10) adds LDAP backup-DC sticky failover**, **`0.2.1` (2026-08-12) fixes a defect that broke AD logins outright** — an AD continuation referral escaped `NovellLdapConnection.Search`, so any `SearchBase` at a domain root failed every login as `ServiceAccountBindFailed` against a perfectly healthy directory. Live-proven against `DC=nam,DC=zimmer,DC=com`; the app-level exposure is closed by the pin bumps. **`FallbackServers` is live-gated** via the local redundant GLAuth pair ([`infra/glauth-redundant/`](infra/glauth-redundant/), primary :3893 + backup :3894 on the dev Mac): HistorianGateway dashboard drill PASS 2026-08-13 (failover, stickiness, walk-back). | Shared `ZB.MOM.WW.Auth` lib | [`components/auth/`](components/auth/) | [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/) |
### Narrative
The auth component is fully populated: a normalized [`spec`](components/auth/spec/SPEC.md), a
proposed [`shared-contract`](components/auth/shared-contract/ZB.MOM.WW.Auth.md), three
[`current-state`](components/auth/current-state/) docs, and an adoption [`GAPS`](components/auth/GAPS.md)
backlog. Common ground = LDAP/GLAuth identity + peppered-HMAC API keys; left per-project =
the authz vocabularies (OPC-UA permissions / gRPC scopes / roles + site-scoping).
The shared library is **built and lives in this repo** at [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/)
(a plain directory of this repo — no nested `.git`, verified 2026-08-07; .NET 10; 4 packages — `Abstractions`, `Ldap`, `ApiKeys`, `AspNetCore`;
250 tests passing + 2 skipped (verified 2026-08-10 at `0.2.0`; was 215+1 at `0.1.5`); feed carries `0.1.0`–`0.2.0`). The implementation plan is at
[`docs/plans/2026-06-01-zb-mom-ww-auth-shared-library.md`](docs/plans/2026-06-01-zb-mom-ww-auth-shared-library.md).
**Adopted across all three apps on 2026-06-02** (auth GAPS #1–#8) on each repo's `feat/adopt-zb-auth` branch —
committed + reviewed, then **fast-forward-merged into the repo's local default (main/master) and PUSHED to origin
(gitea) on 2026-06-03** (in sync; the `feat/*` branches kept locally as history). Cutover: shared `Auth.Ldap`,
`Auth.ApiKeys` (ScadaBridge inbound fully re-architected to the keyId/Bearer model), `IGroupRoleMapper<TRole>` seam,
`Transport`-enum config, canonical `ZbClaimTypes`/`ZbCookieDefaults`, unified dev base DN `dc=zb,dc=local`, and the
canonical-six role vocabulary (with ScadaBridge's accepted auditor/admin SoD collapse). Consumer pins: **all four apps pin `0.3.0` as of 2026-09-03** (commits listed in the table row above, all pushed to origin); all four pinned `0.2.1` from 2026-08-13 before that. Prior history — all four pinned `0.1.5` (verified 2026-08-07): MxGateway via `e107019` 2026-07-18 (earlier bumped `0.1.2`→`0.1.4` 2026-07-09 for the G-2 API-key-expiry verifier enforcement — commit `197731a`; also required implementing the 0.1.3 `IApiKeyAdminStore.SetScopes/SetEnabled` members on a test fake), ScadaBridge `50d79ed1` + HistorianGateway `df211ee` 2026-07-18, OtOpcUa `1adaa2fc` 2026-07-20 (PR #484, family alignment from `0.1.1`). Per-repo detail in [`components/auth/GAPS.md`](components/auth/GAPS.md) +
`docs/plans/2026-06-02-auth-audit-normalization*.md`.
Build/test from `ZB.MOM.WW.Auth/`: `dotnet test` (the `ApiKeys.SqlServer` live suite is gated on `AUTH_SQLSERVER_CONNSTR`, skipped otherwise). Consumer matrix: OtOpcUa → Abstractions+Ldap+AspNetCore;
MxAccessGateway & HistorianGateway → the original four; ScadaBridge → those four **plus `ApiKeys.SqlServer`** (ApiKeys not used by OtOpcUa).
**`0.1.4` (2026-07-09, archreview G-2):** optional `ApiKeyRecord.ExpiresUtc` (nullable = never-expires), `ApiKeyFailure.KeyExpired`, `ApiKeyVerifier` expiry enforcement (inclusive, injected clock), a `CreateKeyAsync(expiresUtc)` overload, and a SQLite **schema v3** additive `expires_utc` column (idempotent `ALTER`; donor v2 DBs upgrade in place, no key invalidated). **All four Auth pkgs published to the Gitea feed at `0.1.4`** (2026-07-09). **HistorianGateway adopted the expiry surface at `0.1.4`** — `apikey create --expires` + dashboard Expires column (Task-10 done). **`0.1.5` (2026-07-18)** is `0.1.4` plus the `SQLitePCLRaw.lib.e_sqlite3 2.1.12` transitive security pin (GHSA-2m69-gcr7-jv3q), no API change; all four apps now pin it (see consumer pins above). **`0.2.0` (2026-08-10) — LDAP backup-DC sticky failover** (plan `docs/plans/2026-08-10-ldap-backup-dc-failover.md`, design `…-design.md`; **4 pkgs published to the feed, restore-verified**; family `Directory.Build.props` now `0.2.0`): one additive `LdapOptions.FallbackServers` list (`"host"` or `"host:port"`, empty default = failover off, single-endpoint behaviour byte-unchanged) makes `LdapAuthService` walk an ordered endpoint list (primary + fallbacks) on **system-side failures only** — connect/TLS, service-account bind, or search. A user-side answer from a healthy directory (`Success`/`UserNotFound`/`AmbiguousUser`/`BadCredentials`/`GroupLookupFailed`) is **final and never retried elsewhere** (re-asking a second DC about a rejected password would multiply one bad-password event into several against the account lockout policy). Endpoint preference is **sticky** — the last endpoint that gave *any* authoritative answer (success **or** a user-side failure) is tried first next time — so a primary outage costs its connect timeout once, not per login; an exhausted walk leaves the preference untouched. Fail-closed contract preserved per-endpoint; boot validation rejects a malformed `FallbackServers` entry naming the field; optional `ILogger<LdapAuthService>` emits a Warning per failed hop (endpoint + stage, no secrets) and an Information on sticky change; wired via `AddZbLdapAuth` (`GetService`, so logging is optional). Motivation: the ZB production directory is NAM AD with two DCs. Unit suite covers the walk/stickiness (14 tests) + env-gated live GLAuth failover test (`ZB_LDAP_IT=1`). **No `Abstractions` contract change beyond the new option; no `LdapAuthFailure` enum change.** App adoption (pin bump to `0.2.0` + authoring `FallbackServers`) is a follow-up.
**`0.2.1` (2026-08-12) — AD continuation referrals no longer fail the search** (**4 pkgs published to the feed, restore-verified**; the assembly restored *from the feed* carries the fix and `0.2.0` does not — checked as a positive control, not by trusting the push). Active Directory answers **any search based at a domain root** with continuation references (to `CN=Configuration`, `DC=ForestDnsZones`, …). With referral following disabled — the default, and what we want, since chasing one would re-bind somewhere we never authenticated — Novell surfaces each by throwing `LdapReferralException` from `Next()`. That escaped `NovellLdapConnection.Search`, and `LdapAuthService` maps a failed search to `ServiceAccountBindFailed`, so **every login against `SearchBase = DC=nam,DC=zimmer,DC=com` failed system-side on both DCs while the directory, the credentials and the service account were all healthy** — ~546 ms, identical on each endpoint, so failover could not help either. Found by the new `tools/LdapProbe` (below) and live-proven fixed against the ZB NAM domain root. The search loop now skips referrals (`ReadEntries(ILdapSearchResults)`, extracted so it is unit-testable through the Novell seam without a live directory) and continues; a 1000-referral cap guards a client that throws without advancing, since that would spin forever inside a fail-closed auth path. **Non-referral faults still propagate** — swallowing those would turn "the directory is broken" into "no such user", which is the wrong answer to give about someone's credentials. 7 new tests (`NovellSearchReferralTests`), **6 verified red against the pre-fix code**, the seventh being the non-referral control that must stay green; suite 257 pass / 2 skip / 0 fail. **No `Abstractions` change; no config change.** **Consumer impact: an app on `0.1.5` cannot authenticate against an AD domain root at all**, so the pin bump is a functional fix, not housekeeping. **Closed 2026-08-13: all four apps adopted `0.2.1`** (see the table row for commits), and `FallbackServers` was live-gated the same day against the redundant local GLAuth pair (`infra/glauth-redundant/`).
**`0.3.0` (2026-09-02) — `ZB.MOM.WW.Auth.ApiKeys.SqlServer`, a SQL Server provider for the API-key store** (design `ScadaBridge/docs/plans/2026-09-02-inbound-api-key-shared-store-design.md`; **5 pkgs published to the feed**, `ApiKeys.SqlServer` search-verified from the ScadaBridge checkout; family `Directory.Build.props` now `0.3.0`). Motivation: `Auth.ApiKeys`' SQLite store is a per-node file, so on a two-node active/standby host (ScadaBridge central) a key minted on one node exists only there and a failover 401s every inbound caller (ScadaBridge deferred-work row 108). The new package implements `IApiKeyStore`/`IApiKeyAdminStore`/`IApiKeyAuditStore` over `Microsoft.Data.SqlClient` in a `zbauth` schema (v1: `schema_version`, `api_keys`, `api_key_audit`; all timestamps `DATETIMEOFFSET(7)`, tick-exact) with a concurrent-boot-safe migrator (Serializable tx, retry on 1205/2714/1913/2627 with **jittered** backoff — the Secrets replicator's flat `100*attempt` backoff exhausted five retries about once per sixty 8-way boots in the port's soak test, so the same latent defect is an open follow-up there → #18) and a `SqliteApiKeyStoreImporter` that copies an existing SQLite file into the schema insert-where-absent (idempotent, so both nodes of a pair can import their own file and the result is the union). Wiring: `services.AddZbApiKeyAuthSqlServer(config, apiKeySection, sqlServerSection)` registers the SQL Server stores + migrator **before** delegating to `AddZbApiKeyAuth`, whose `TryAdd*` registrations then yield (same displacement mechanism as Secrets 0.5.0). One `Abstractions` addition, additive: `IApiKeyStoreMigrator`, which `SqliteAuthStoreMigrator` now implements and `ApiKeyAdminCommands` accepts via a new ctor (old `SqliteAuthStoreMigrator` ctor retained — the three `0.2.1` consumers compile unchanged). Store semantics are pinned to the SQLite contract tests re-run live (mark-used skips revoked keys, delete only removes revoked keys, rotate clears last-used/revoked, list newest-first). 92 tests in the new project, 351 across the solution, 0 failed. A DBA-run copy of the DDL ships at `docs/sql/zbauth-schema.sql`.
**`tools/LdapProbe`** (`ldapprobe`, not packable, outside the Auth solution) is the diagnostic that found the above: it drives the **real** `LdapAuthService` so its verdict is what the four apps produce, then separately queries the directory for what the library cannot report — full group DNs, **nested** groups via `LDAP_MATCHING_RULE_IN_CHAIN`, the **primary group** (which AD omits from `memberOf`, so it can never be a role group), group type (security vs distribution), decoded `userAccountControl`, referral counts, and the TLS chain with key sizes. `--list-groups '<pat>'` enumerates every group in the directory matching a pattern, which a membership dump structurally cannot do. Findings recorded in [`ldap_setup.md`](ldap_setup.md), including the **`UG_WW_*` Wonderware group convention (39 groups)** that partly overturns that doc's earlier "no group→role convention exists" claim — it was true of Ignition, false of the domain.
**`0.5.0` (2026-11-12, ScadaBridge#46) — passwordless group lookup; first published version carrying 0.4.2–0.4.4.** New `Abstractions` contract `ILdapGroupLookup.GetUserGroupsAsync(username, ct)` → `LdapGroupLookupResult` / `LdapGroupLookupStatus` (`Found`, `UserNotFound`, `UserDisabled` (AD `userAccountControl` bit 2), `AmbiguousUser`, `DirectoryUnavailable`, `NotSupported` (`BindMode=User` / blank service DN / foreign `ILdapAuthService`), `ProviderDisabled`). Implemented by `LdapAuthService` (service-account bind + `UserNameAttribute` search; same extraction/canonicalisation as sign-in; the endpoint walk was factored into one generic `WalkEndpoints<T>` shared by both paths, so failover and the sticky preference are common). `AddZbLdapAuth` registers it as the same singleton. Tests: 30 unit (`LdapGroupLookupTests`, 6 mutations all killed) + 2 DI + 6 live GLAuth (`GLAuthGroupLookupTests`, run against the redundant local pair incl. two-live-endpoint failover; failover mutation killed live). **scadaproj#51 closed by a live NAM run (24/24)** — see README §0.5.0/§0.4.4 for what was proven; the identity check's non-vacuity was shown by mutating the `msDS-PrincipalName` comparison (user-bind sign-ins then fail). Consumers: ScadaBridge adopts 0.5.0 (#46); OtOpcUa / mxgw / HistorianGateway / BTDB stay on their pins.
**`0.4.4` (first published in 0.5.0, scadaproj#40, Auth-007):** `BindMode=User` now proves the entry whose groups it returns is the account that bound — RFC 4532 Who-am-I (`dn:` → DN match; AD `u:DOMAIN\name` → `sAMAccountName` match), falling back to the bind DN only for a DN template (GLAuth has no Who-am-I); otherwise `GroupLookupFailed`. `{0}` is RFC 4514-escaped in DN templates. Before the fix a user could sign in with another account's groups whenever the UPN/DN bind and the `UserNameAttribute` search named different accounts — reproduced live against a throwaway GLAuth (`tests/ZB.MOM.WW.Auth.Ldap.Tests/Integration/glauth-userbind/`, `ZB_LDAP_USERBIND_IT=1`, port 3897): pre-fix `mallory` signed in with `Admins`. **Consumer impact:** AD + down-level/UPN template unchanged for consistent accounts (BTDB Manager is the only user-bind consumer); non-AD user-bind needs a DN template that yields the entry's DN exactly as searched (GLAuth: `cn={0},ou=<group>,ou=users,<base>`). README §0.4.4.
**`0.4.4`, continued (first published in 0.5.0, scadaproj#46 + #50):** still `0.4.4`.
- **Auth-008 (`ApiKeys.SqlServer`):** over-length key records are refused with `ArgumentException`; an over-64 key-id lookup answers not-found without querying; every `key_id` predicate adds an exact `VARBINARY` match, so lookups are case- and trailing-space-exact like SQLite. No schema change. `ApiKeyImportResult` gains the `init` lists `KeyIdCollisions` and `KeysRejected`, and `KeysSkipped` now counts exact duplicates only. Audit text is still truncated to 64 characters, deliberately (documented).
- **Auth-009:** the canonical username is the `UserNameAttribute` value matching the typed name, ignoring case, not `values[0]`.
- **Auth-010:** the new `ApiKeyFailure.StoreUnavailable` (appended) is returned when `FindByKeyIdAsync` throws; only cancellation still throws.
- **#50 (user bind, AD forests):** for a `u:DOMAIN\name` Who-am-I answer, the entry must be that domain's account. Where AD offers `msDS-PrincipalName` (a base read through the new internal `ILdapConnection.Read`), it must equal the answer. Otherwise the name must have exactly one holder under `SearchBase`. Live-verified against the NAM AD 2026-11-12 (scadaproj#51, see 0.5.0).
- **Consumer-facing:** a new enum value; SQL Server key ids now match exactly; over-length creates throw; the importer reports collisions and rejections.
- Suites: 363 passed / 81 skipped offline; 440 passed / 4 skipped (LDAP live) with `AUTH_SQLSERVER_CONNSTR`, against a throwaway SQL Server 2022.
**`0.4.3` (unpublished, scadaproj#26):** `Microsoft.Data.Sqlite` 10.0.7 -> 10.0.13 (efcore#39009 pool fault); `SQLitePCLRaw.lib.e_sqlite3` transitive pin 2.1.12 -> 2.1.13 (10.0.13 floors 2.1.13). No API change.
**`0.4.2` (unpublished, scadaproj#23 + #22):** `ZB.MOM.WW.Auth.ApiKeys.ApiKeyPepperUnavailableException : InvalidOperationException` (message still `"pepper unavailable"`) is now thrown by `ApiKeyAdminCommands` create/rotate when the pepper is missing, so consumers can catch it by type; existing `catch (InvalidOperationException)` blocks keep working (only exact-type assertions like xunit `ThrowsAsync<InvalidOperationException>` need updating). **Release note: consumers can drop their own `IApiKeyPepperProvider` pre-checks** — mxaccessgw's `DashboardApiKeyManagementService` and any similar code. Also pins `System.Security.Cryptography.Pkcs 9.0.21` (transitive, via SqlClient 6.0.2) to clear NuGetAudit NU1902/NU1903. Not yet published to the feed.
+10 -1
View File
@@ -5,7 +5,16 @@
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<LangVersion>latest</LangVersion>
<Version>0.1.4</Version>
<!-- 0.4.0: opt-in LdapOptions.BindMode = User — authenticate by binding as the signing-in user
(UserBindTemplate) and read their own groups on the same connection; no service account.
ServiceAccount stays the default, so existing consumers need no change. -->
<!-- 0.4.1: Username canonicalised from the entry's UserNameAttribute; empty passwords refused
in both bind modes (ServiceAccount-mode behaviour change); template docs prefer EXAMPLE\{0}. -->
<!-- 0.4.2: typed ApiKeyPepperUnavailableException (: InvalidOperationException) for a missing pepper on
create/rotate; patched System.Security.Cryptography.Pkcs transitive pin (SqlServer package). -->
<!-- 0.5.0: passwordless group lookup — ILdapGroupLookup.GetUserGroupsAsync (service account; shares the
endpoint walk / sticky preference / TLS policy with AuthenticateAsync). Includes the unpublished 0.4.2–0.4.4. -->
<Version>0.5.0</Version>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
+20 -1
View File
@@ -2,6 +2,8 @@
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
<!-- Enable transitive pinning so the security override below (SQLitePCLRaw native lib) takes effect. -->
<CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
</PropertyGroup>
<ItemGroup>
@@ -9,7 +11,23 @@
<PackageVersion Include="Novell.Directory.Ldap.NETStandard" Version="3.6.0" />
<!-- Data -->
<PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.7" />
<PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.13" />
<!-- Transitive security pin: Microsoft.Data.Sqlite pulled SQLitePCLRaw.lib.e_sqlite3 2.1.11 (10.0.7); 10.0.13 floors 2.1.13 (scadaproj#26),
which carries advisory GHSA-2m69-gcr7-jv3q (NU1903). Pin the patched 2.1.13 native lib. -->
<PackageVersion Include="SQLitePCLRaw.lib.e_sqlite3" Version="2.1.13" />
<!-- Shared SQL-Server API-key store (ZB.MOM.WW.Auth.ApiKeys.SqlServer). 6.0.2 matches the
family pin used by ZB.MOM.WW.Secrets' SQL-Server store, so a consumer taking both gets one
SqlClient rather than a downgrade warning. -->
<PackageVersion Include="Microsoft.Data.SqlClient" Version="6.0.2" />
<!-- 9.0.4, not 9.0.0: Microsoft.Data.SqlClient 6.0.2 pulls System.Configuration.ConfigurationManager
9.0.4, which requires ProtectedData >= 9.0.4. With transitive pinning on, the lower central
version is a hard NU1109 downgrade error rather than a silent resolve. -->
<PackageVersion Include="System.Security.Cryptography.ProtectedData" Version="9.0.4" />
<!-- Transitive security pin (scadaproj#22): Microsoft.Data.SqlClient 6.0.2 pulls
System.Security.Cryptography.Pkcs 9.0.4, which carries GHSA-846f-f764-76mx (high) and
GHSA-2fmv-rv2c-59x7 (moderate) and fails restore under warnings-as-errors (NU1902/NU1903).
Pin the patched 9.0.21 (first fixed in the 9.0 line; 9.0.0-9.0.20 and 10.0.0-10.0.12 are all affected). -->
<PackageVersion Include="System.Security.Cryptography.Pkcs" Version="9.0.21" />
<!-- Extensions -->
<PackageVersion Include="Microsoft.Extensions.Options" Version="10.0.7" />
@@ -19,6 +37,7 @@
<PackageVersion Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.7" />
<PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.7" />
<PackageVersion Include="Microsoft.Extensions.Hosting.Abstractions" Version="10.0.7" />
<PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.7" />
<!-- ASP.NET Core Authentication / Authorization -->
<PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.7" />
+75 -6
View File
@@ -11,17 +11,18 @@ Authentication and authorisation libraries for the **ZB.MOM.WW SCADA family** (O
| `ZB.MOM.WW.Auth.Abstractions` | Auth contracts, canonical role constants, and shared types (`LdapOptions`, `LdapAuthResult`, `ILdapAuthService`, `IApiKeyStore`). No runtime dependencies beyond the BCL. | — |
| `ZB.MOM.WW.Auth.Ldap` | LDAP authentication service: bind-then-search-then-bind against GLAuth or Active Directory; RFC 4514-aware group extraction; fail-closed. | `Abstractions`, `Novell.Directory.Ldap.NETStandard` |
| `ZB.MOM.WW.Auth.ApiKeys` | SQLite-backed API-key store with **pepper-keyed HMAC-SHA256** secret hashing, rotation, and audit log. DI wiring is `AddZbApiKeyAuth`; an opt-in `MigrationHostedService` runs schema migrations on startup. | `Abstractions`, `Microsoft.Data.Sqlite` |
| `ZB.MOM.WW.Auth.ApiKeys.SqlServer` | SQL Server-backed API-key store sharing **one row set** across clustered hosts (e.g. a central pair), instead of each node keeping its own SQLite file. DI wiring is `AddZbApiKeyAuthSqlServer(config, apiKeySection, sqlServerSection)`, called **instead of** `AddZbApiKeyAuth` (it calls that internally). Also ships `SqliteApiKeyStoreImporter` — a one-shot per-node SQLite → shared store copy a host runs once at boot. | `Abstractions`, `ApiKeys`, `Microsoft.Data.SqlClient` |
| `ZB.MOM.WW.Auth.AspNetCore` | ASP.NET Core wiring for the **LDAP** provider only: `AddZbLdapAuth` (binds + start-time-validates `LdapOptions`, registers `ILdapAuthService`), plus `ZbCookieDefaults.Apply` (hardened cookie helper the consumer calls itself) and `ZbClaimTypes` constants. It does **not** wire API keys or cookie middleware — API-key DI is `AddZbApiKeyAuth` in the `ApiKeys` package. | `Abstractions`, `Ldap`, `Microsoft.AspNetCore.App` |
---
## Consumer Matrix
| Consumer | Abstractions | Ldap | ApiKeys | AspNetCore |
|---|:---:|:---:|:---:|:---:|
| **OtOpcUa** | yes | yes | — | yes |
| **MxAccessGateway** | yes | yes | yes | yes |
| **ScadaBridge** | yes | yes | yes | yes |
| Consumer | Abstractions | Ldap | ApiKeys | ApiKeys.SqlServer | AspNetCore |
|---|:---:|:---:|:---:|:---:|:---:|
| **OtOpcUa** | yes | yes | — | — | yes |
| **MxAccessGateway** | yes | yes | yes | — | yes |
| **ScadaBridge** | yes | yes | yes | yes (central pair, 2026-09-02) | yes |
`ApiKeys` is NOT used by OtOpcUa (that app authenticates human operators via LDAP + cookies only; machine-to-machine access is out of scope).
@@ -29,7 +30,73 @@ Authentication and authorisation libraries for the **ZB.MOM.WW SCADA family** (O
## Versioning
All four packages are versioned **lockstep** from `Directory.Build.props`. The current release is **0.1.4**. A single version bump in `Directory.Build.props` bumps all four packages simultaneously — consumers should reference the same version for all ZB.MOM.WW.Auth packages.
All five packages are versioned **lockstep** from `Directory.Build.props`. The current release is **0.5.0**. A single version bump in `Directory.Build.props` bumps all five packages simultaneously — consumers should reference the same version for all ZB.MOM.WW.Auth packages.
### 0.5.0 — passwordless group lookup (`ILdapGroupLookup`, ScadaBridge#46)
Includes every unpublished 0.4.2–0.4.4 change below; **0.5.0 is the first published version carrying them** (scadaproj#51 live-verified them against the NAM AD before publishing).
- **New `Abstractions` contract:** `ILdapGroupLookup.GetUserGroupsAsync(string username, CancellationToken ct)` → `LdapGroupLookupResult(Status, Username, DisplayName, Groups)`, with `LdapGroupLookupStatus` = `Found` | `UserNotFound` | `UserDisabled` | `AmbiguousUser` | `DirectoryUnavailable` | `NotSupported` | `ProviderDisabled`. It re-reads a known user's groups **without their password** — e.g. to refresh an active session when directory membership changes.
- **`LdapAuthService` implements it** (`AddZbLdapAuth` registers `ILdapGroupLookup` as the *same* singleton, so sign-in and lookup share one sticky endpoint preference). It binds as the **service account**, searches `UserNameAttribute` under `SearchBase`, and returns the same group set, canonical username and display name `AuthenticateAsync` would — through the same group extraction, canonicalisation, endpoint walk (`FallbackServers`, system-side failures only), timeouts and TLS policy. The name is normalised as `AuthenticateAsync` normalises it in `ServiceAccount` mode (trimmed).
- **Outcomes:** connect/TLS, service-account bind or search failing on every endpoint → `DirectoryUnavailable` (a statement about the directory, never about the user). `UserDisabled` comes from AD's `userAccountControl` ACCOUNTDISABLE bit (requested automatically; directories without the attribute never report it). `Found` may carry **zero** groups — sign-in refuses such a user, the caller decides. `BindMode = User` (no service account) and a blank `ServiceAccountDn` answer `NotSupported` without touching the network; `Enabled = false` answers `ProviderDisabled`. Never throws (cancellation at entry only); credentials are never logged.
- A host that registers its own `ILdapAuthService` (a dev stub, a decorator) gets a lookup that answers `NotSupported`.
- **Consumer impact:** additive. No existing signature or enum value changed in 0.5.0 itself; the 0.4.2–0.4.4 notes below still apply to anyone coming from 0.4.1.
- **Live-verified 2026-11-12 against the NAM AD** (both DCs, LDAPS 636, StartTLS 389, the Global Catalog 3269 with a forest-wide base): lookup groups == sign-in groups (176), a real disabled account → `UserDisabled`, unknown → `UserNotFound`, failover to either DC, all-dead / wrong service password → `DirectoryUnavailable`, `User` mode → `NotSupported`. Plus GLAuth (redundant local pair) integration tests `GLAuthGroupLookupTests`.
### 0.4.4 — user bind proves the bound account is the one whose groups it returns (first published in 0.5.0, scadaproj#40)
- **Security fix (Auth-007), `BindMode = User` only.** The bind name (`UserBindTemplate`) and the group search (`UserNameAttribute`) are two separate directory lookups and could name two accounts — e.g. AD resolves `jsmith@corp.com` to the account with that explicit UPN while `(sAMAccountName=jsmith)` finds a different one, so a user could sign in with another account's groups. The service now only accepts the entry it found when it is provably the account that bound:
- it asks the directory with RFC 4532 **Who-am-I** after the bind; a `dn:<dn>` answer must equal the entry's DN (`distinguishedNameMatch`), and AD's `u:DOMAIN\name` answer must equal the entry's `sAMAccountName` (requested automatically);
- a server without Who-am-I (GLAuth answers protocol error 2) is supported only with a **DN template** (contains `=`), whose bind DN must equal the entry's DN;
- anything else — a mismatch, an unanswered Who-am-I with a UPN or down-level template — is `GroupLookupFailed`, logged at Warning, and never retried on a fallback endpoint.
- **`{0}` is now RFC 4514-escaped in a DN template**, so a typed name such as `x,ou=Admins` cannot rewrite the bind DN.
- **Behaviour change for consumers:** AD with a down-level or UPN template is unaffected for accounts whose bound identity and searched entry agree (AD has supported Who-am-I since Windows Server 2003). A UPN template now refuses accounts whose UPN prefix differs from `sAMAccountName` instead of risking the wrong account. A **non-AD directory** in `User` mode needs either Who-am-I support or a DN template that yields the entry's DN *exactly as the search returns it* — for GLAuth that is `cn={0},ou=<group>,ou=users,<base>`, not `cn={0},ou=<group>,<base>`. ServiceAccount mode is unchanged.
- The validator's `UserBindTemplate` message now leads with `EXAMPLE\{0}`. No `Abstractions` contract change (XML docs only).
- **AD forests (scadaproj#50).** `sAMAccountName` is unique per *domain*, so with a search base that spans a forest (a Global Catalog) a matching `sAMAccountName` alone could be another domain's account of the same name. For AD's `u:DOMAIN\name` answer the entry must now also be proven to be that domain's account:
- where the directory computes `msDS-PrincipalName` for the entry (a base read; AD's `DOMAIN\name`, derived from `objectSid`), it must equal the Who-am-I answer, domain included;
- otherwise the name must have exactly one holder under `SearchBase`, and it must be the entry found — no extra search is made when `UserNameAttribute` is `sAMAccountName` and the user typed the bound name, because the user search already proved that. Two holders → `GroupLookupFailed`.
- A single-domain AD (BTDB Manager) is unaffected. **Live-verified against the NAM AD 2026-11-12 (scadaproj#51):** `User` mode with `NAM\{0}` and the UPN template both sign in with the same groups as `ServiceAccount` mode; AD answers Who-am-I as `u:NAM\<sAMAccountName>` and serves `msDS-PrincipalName` on a base read (DC and Global Catalog); a forest-wide Global Catalog base (`DC=zimmer,DC=com`) signs in correctly; and mutating the `msDS-PrincipalName` comparison makes every user-bind sign-in fail `GroupLookupFailed`, so that check is what decides against real AD.
- **`ApiKeyFailure.StoreUnavailable` (Auth-010, `Abstractions` addition).** `ApiKeyVerifier.VerifyAsync` no longer lets a key-store fault escape: a `FindByKeyIdAsync` that throws (shared SQL Server unreachable, a SQLite I/O fault) returns `Succeeded = false` with the new `StoreUnavailable` failure, so it takes the host's normal — audited — auth-failure path instead of an unhandled 500 / gRPC `Unknown`. Cancellation still throws. The value is appended, so existing numeric values are unchanged; a host may answer it with 503 rather than 401. A misconfigured `SqlServerApiKeyOptions` still throws when the store is first resolved (outside `VerifyAsync`).
- **SQL Server store: no truncation, exact key ids (Auth-008).** The `ApiKeys.SqlServer` stores now behave like the SQLite store they port:
- `CreateAsync` throws `ArgumentException` for a key id over 64, prefix over 16 or display name over 256 characters (it used to store them silently truncated), and every lookup of an over-64-character key id answers "not found" without querying (a truncated parameter could match a different key sharing its first 64 characters).
- Key-id matching is **exact** — case- and trailing-space-sensitive — via a binary comparison added to every `key_id` predicate; the primary-key seek is unchanged and there is **no schema change**. A token presented with a case-altered key id (`LINE1` for `line1`) now fails `KeyNotFound` instead of resolving.
- `SqliteApiKeyStoreImporter` reports instead of hiding: `ApiKeyImportResult.KeyIdCollisions` lists source keys whose id differs only in case from one already in SQL Server (the primary key follows the database collation and cannot hold both — re-mint those keys), and `KeysRejected` lists over-length keys; neither is counted in `KeysSkipped` any more. Both are new `init` properties, so existing code is unaffected.
- Audit text (`key_id`, `event_type`, `remote_address`) is still truncated to 64 characters — deliberately, and now documented: an audit append runs after the action it records and must not fail it.
- **Canonical username from a multi-valued attribute (Auth-009).** `LdapAuthResult.Username` is now the `UserNameAttribute` value that equals the typed name ignoring case — `cn: [John Smith, jsmith]` signs `jsmith` in as `jsmith`, not whichever value the server lists first. The first value is used only when none matches. Both bind modes.
### 0.4.1 — LDAP review fixes
- **Canonical username (both modes):** the search now also requests `UserNameAttribute`, and `LdapAuthResult.Username` is the entry's first value of it (the directory's spelling), so `JDoe` and `jdoe` sign in as one identity in consumers' audit columns. Falls back to the normalised typed name when the entry has no such value.
- **Behaviour change for `ServiceAccount`-mode consumers:** an empty (or null) password is now refused by the library as `BadCredentials` before any network call, in both bind modes. Previously only `User` mode refused it; in `ServiceAccount` mode the re-bind as the user's DN with an empty password is an unauthenticated bind that AD reports as success, so a consumer without its own edge check admitted anyone.
- **Template guidance:** prefer the down-level `UserBindTemplate` `EXAMPLE\{0}` — it maps exactly to the `sAMAccountName` the group search uses. A UPN template (`{0}@example.com`) is only correct where every account's UPN prefix equals its `sAMAccountName`; AD resolves UPN binds against the explicit `userPrincipalName`, so a mismatch can fail sign-in or bind a different account than the one whose groups are read.
- No `Abstractions` contract change.
### 0.4.0 — LDAP sign-in by user bind (opt-in)
- **`LdapOptions.BindMode`** (`ServiceAccount` default | `User`), **`UserBindTemplate`** (`{0}` = the login name, e.g. `EXAMPLE\{0}` — preferred, see 0.4.1 — or `{0}@example.com`) and **`AcceptDomainQualifiedNames`** (default `true`).
- In `User` mode `LdapAuthService` binds as the user; success authenticates them and the same connection reads their entry (`UserNameAttribute`, `DisplayNameAttribute`, `GroupAttribute`). No `ServiceAccountDn` / `ServiceAccountPassword` is needed or validated.
- Failure mapping: empty password or an unusable name → `BadCredentials` with no network call (AD treats an empty-password simple bind as an unauthenticated success). Bind result 49 → `BadCredentials`, final — never retried on a fallback DC, so one wrong password is one lockout strike. Any other bind error, a connect failure or a search failure → the system-side bucket (`ServiceAccountBindFailed`) and the next endpoint. Zero/several entries or no groups after a good bind → `GroupLookupFailed`.
- `DOMAIN\name` / `name@suffix` are reduced to `name` (or refused when `AcceptDomainQualifiedNames` is `false`), so the result's `Username` has one spelling (0.4.1 also canonicalises its case from the entry).
- No `Abstractions` contract change beyond the new enum and option properties; `ServiceAccount` mode is unchanged.
- `UserBindTemplate` output is used verbatim as the bind name, so use a down-level (`EXAMPLE\{0}`, preferred) or UPN (`{0}@example.com`, only where every UPN prefix equals the `sAMAccountName`) template; a DN template is not escaped.
### 0.3.0 — SQL Server API-key store (ScadaBridge central pair)
- **`IApiKeyStoreMigrator`** added to `Abstractions`: creates or upgrades an API-key store's schema; idempotent and safe to run concurrently from several nodes. `SqliteAuthStoreMigrator` implements it unchanged. `AddZbApiKeyAuth` registers the SQLite implementation via `TryAdd`, so a provider that registers its own migrator first (see below) wins — that ordering is the whole mechanism by which a different backend is swapped in.
- **New package `ZB.MOM.WW.Auth.ApiKeys.SqlServer`** + `AddZbApiKeyAuthSqlServer(config, apiKeySection, sqlServerSection)`, called instead of `AddZbApiKeyAuth` (it calls it internally after registering the SQL Server stores and migrator first).
- **`zbauth` schema v1** (three tables: `schema_version`, `api_keys`, `api_key_audit`; `DATETIMEOFFSET(7)` timestamps). `SqlServerApiKeyStoreMigrator` is concurrent-boot safe — a central pair's two nodes both migrate at every boot — with retry on SQL error numbers 1205/2714/1913/2627 and jittered backoff (measured: the flat backoff it replaced exhausted its retries roughly 1 in 60 eight-way boots). DBA-facing DDL: `docs/sql/zbauth-schema.sql`.
- **`SqliteApiKeyStoreImporter`** — idempotent insert-where-not-exists copy of an existing node's per-node SQLite keys and audit rows into the shared store; a row already present in SQL Server is never modified, so running it from both nodes of a pair converges on the union of their files.
- **`ApiKeyAdminCommands`** gained a ctor taking `IApiKeyStoreMigrator`; the existing ctor taking the concrete `SqliteAuthStoreMigrator` is retained (MxAccessGateway, HistorianGateway and ScadaBridge all construct it that way).
- SQLite remains the default store; **existing consumers need no code change to move to 0.3.0**.
- Live tests for the SQL Server package are gated on `AUTH_SQLSERVER_CONNSTR` and skip (not fail) when it is unset.
### 0.2.1 — LDAP AD continuation-referral fix
- `NovellLdapConnection.Search` now skips Active Directory continuation referrals (`LdapReferralException` from `Next()`) instead of letting one fail the whole search — a `SearchBase` at a domain root made every login fail as `ServiceAccountBindFailed` against a healthy directory. Non-referral faults still propagate untouched.
### 0.2.0 — version bump only
- No functional change; bumped the lockstep family version ahead of the 0.2.1 LDAP fix.
### 0.1.4 — API-key expiry (archreview G-2)
@@ -63,6 +130,8 @@ The GLAuth integration test (`GLAuthIntegrationTests`) is **skipped by default**
--filter "FullyQualifiedName~GLAuthIntegrationTests"
```
The 0.5.0 group-lookup tests (`GLAuthGroupLookupTests`) use the same variables plus an optional `ZB_LDAP_FALLBACK=host:port` for a second live directory (e.g. the redundant pair in `infra/glauth-redundant`, `:3893` + `:3894`, service account `cn=serviceaccount,dc=zb,dc=local`).
All other variables (`ZB_LDAP_SERVER`, `ZB_LDAP_PORT`, `ZB_LDAP_BASE`, `ZB_LDAP_USERATTR`) default to sensible GLAuth values and are optional. The test also probes TCP reachability before attempting auth and skips if the server is not contactable.
---
+2
View File
@@ -2,11 +2,13 @@
<Folder Name="/src/">
<Project Path="src/ZB.MOM.WW.Auth.Abstractions/ZB.MOM.WW.Auth.Abstractions.csproj" />
<Project Path="src/ZB.MOM.WW.Auth.ApiKeys/ZB.MOM.WW.Auth.ApiKeys.csproj" />
<Project Path="src/ZB.MOM.WW.Auth.ApiKeys.SqlServer/ZB.MOM.WW.Auth.ApiKeys.SqlServer.csproj" />
<Project Path="src/ZB.MOM.WW.Auth.AspNetCore/ZB.MOM.WW.Auth.AspNetCore.csproj" />
<Project Path="src/ZB.MOM.WW.Auth.Ldap/ZB.MOM.WW.Auth.Ldap.csproj" />
</Folder>
<Folder Name="/tests/">
<Project Path="tests/ZB.MOM.WW.Auth.ApiKeys.Tests/ZB.MOM.WW.Auth.ApiKeys.Tests.csproj" />
<Project Path="tests/ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests/ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests.csproj" />
<Project Path="tests/ZB.MOM.WW.Auth.AspNetCore.Tests/ZB.MOM.WW.Auth.AspNetCore.Tests.csproj" />
<Project Path="tests/ZB.MOM.WW.Auth.Ldap.Tests/ZB.MOM.WW.Auth.Ldap.Tests.csproj" />
</Folder>
+7 -1
View File
@@ -6,4 +6,10 @@
set -euo pipefail
dotnet pack -c Release -o ./artifacts
# cd to the repo root and name the solution + an absolute output path: `dotnet pack` with
# neither a project argument nor a fixed working directory packs whatever solution happens
# to sit in the CALLER's directory (the bug behind the LocalDb feed incident, 0038d46).
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$REPO_ROOT"
dotnet pack ZB.MOM.WW.Auth.slnx -c Release -o "$REPO_ROOT/artifacts"
+13 -2
View File
@@ -16,9 +16,20 @@ set -euo pipefail
: "${GITEA_NUGET_SOURCE:?set GITEA_NUGET_SOURCE to your Gitea NuGet feed URL}"
: "${GITEA_NUGET_KEY:?set GITEA_NUGET_KEY to your Gitea access token}"
dotnet pack -c Release -o ./artifacts
# Named solution, named output, and a cd to the repo root, all for one reason: `dotnet pack`
# with neither a project argument nor a fixed working directory packs whatever solution
# happens to sit in the CALLER's directory — and then pushes it to a live feed under this
# script's name. Invoked by absolute path from another repo's checkout, the relative form
# packed and published 25 unrelated packages (LocalDb's copy of this script, fixed in
# 0038d46; recovered with `dotnet nuget delete`, but only because the token happened to
# carry delete rights). A publish script must be unambiguous about WHAT it publishes no
# matter where it is run.
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$REPO_ROOT"
dotnet nuget push "./artifacts/*.nupkg" \
dotnet pack ZB.MOM.WW.Auth.slnx -c Release -o "$REPO_ROOT/artifacts"
dotnet nuget push "$REPO_ROOT/artifacts/*.nupkg" \
--source "$GITEA_NUGET_SOURCE" \
--api-key "$GITEA_NUGET_KEY" \
--skip-duplicate
+69
View File
@@ -0,0 +1,69 @@
-- ZB.MOM.WW.Auth.ApiKeys.SqlServer — shared API-key schema, version 1.
--
-- For DBAs whose application login lacks DDL rights. The host normally provisions this itself at
-- startup (SqlServerApiKeyStoreMigrator, which runs the identical statements and is safe to run
-- concurrently from every node); where the app login may only read and write rows, run this script
-- once against the target database instead. The migrator then finds the version row already at the
-- version it supports and does nothing further beyond re-stamping applied_utc.
--
-- The schema name is hard-coded to zbauth here — the default of SqlServerApiKeyOptions.Schema. If a
-- deployment overrides that option, substitute the name in every bracketed identifier below.
--
-- Kept byte-for-byte consistent with SqlServerAuthSchema.CreateSchemaDdl apart from that
-- substitution and the literal version row at the end; change both together.
IF NOT EXISTS (SELECT 1 FROM sys.schemas WHERE name = N'zbauth')
EXEC(N'CREATE SCHEMA [zbauth]');
IF OBJECT_ID(N'[zbauth].[schema_version]', N'U') IS NULL
CREATE TABLE [zbauth].[schema_version] (
id INT NOT NULL CONSTRAINT PK_zbauth_schema_version PRIMARY KEY CHECK (id = 1),
version INT NOT NULL,
applied_utc DATETIMEOFFSET(7) NOT NULL
);
IF OBJECT_ID(N'[zbauth].[api_keys]', N'U') IS NULL
CREATE TABLE [zbauth].[api_keys] (
key_id NVARCHAR(64) NOT NULL CONSTRAINT PK_zbauth_api_keys PRIMARY KEY,
key_prefix NVARCHAR(16) NOT NULL,
secret_hash VARBINARY(64) NOT NULL,
display_name NVARCHAR(256) NOT NULL,
scopes NVARCHAR(MAX) NOT NULL,
constraints NVARCHAR(MAX) NULL,
created_utc DATETIMEOFFSET(7) NOT NULL,
last_used_utc DATETIMEOFFSET(7) NULL,
revoked_utc DATETIMEOFFSET(7) NULL,
expires_utc DATETIMEOFFSET(7) NULL
);
IF OBJECT_ID(N'[zbauth].[api_key_audit]', N'U') IS NULL
CREATE TABLE [zbauth].[api_key_audit] (
audit_id BIGINT IDENTITY(1,1) NOT NULL CONSTRAINT PK_zbauth_api_key_audit PRIMARY KEY,
key_id NVARCHAR(64) NULL,
event_type NVARCHAR(64) NOT NULL,
remote_address NVARCHAR(64) NULL,
created_utc DATETIMEOFFSET(7) NOT NULL,
details NVARCHAR(MAX) NULL
);
IF NOT EXISTS (
SELECT 1 FROM sys.indexes
WHERE name = N'ix_api_keys_revoked_utc'
AND object_id = OBJECT_ID(N'[zbauth].[api_keys]'))
CREATE INDEX ix_api_keys_revoked_utc
ON [zbauth].[api_keys] (revoked_utc);
IF NOT EXISTS (
SELECT 1 FROM sys.indexes
WHERE name = N'ix_api_key_audit_key_id_created_utc'
AND object_id = OBJECT_ID(N'[zbauth].[api_key_audit]'))
CREATE INDEX ix_api_key_audit_key_id_created_utc
ON [zbauth].[api_key_audit] (key_id, created_utc);
MERGE [zbauth].[schema_version] AS target
USING (SELECT 1 AS id, 1 AS version, SYSDATETIMEOFFSET() AS applied_utc) AS source
ON target.id = source.id
WHEN MATCHED THEN
UPDATE SET version = source.version, applied_utc = source.applied_utc
WHEN NOT MATCHED THEN
INSERT (id, version, applied_utc) VALUES (1, source.version, source.applied_utc);
@@ -8,7 +8,35 @@ public sealed record ApiKeyOptions
public bool RunMigrationsOnStartup { get; init; } = true;
}
public enum ApiKeyFailure { MissingOrMalformed, KeyNotFound, KeyRevoked, PepperUnavailable, SecretMismatch, KeyExpired }
/// <summary>Why an API-key verification failed. New values are only ever appended, so stored or logged numeric values keep their meaning.</summary>
public enum ApiKeyFailure
{
/// <summary>No credential, or one that does not parse as <c>&lt;prefix&gt;_&lt;keyId&gt;_&lt;secret&gt;</c>.</summary>
MissingOrMalformed,
/// <summary>No key with the presented key id exists.</summary>
KeyNotFound,
/// <summary>The key exists but has been revoked.</summary>
KeyRevoked,
/// <summary>The pepper could not be resolved, so no key can be verified.</summary>
PepperUnavailable,
/// <summary>The presented secret does not match the stored hash.</summary>
SecretMismatch,
/// <summary>The key exists but its absolute expiry has passed.</summary>
KeyExpired,
/// <summary>
/// The key store could not be queried (database unreachable, misconfigured, I/O fault), so the
/// credential could be neither accepted nor rejected on its merits. Added in 0.4.4 (Auth-010);
/// before it, the store's exception escaped <c>VerifyAsync</c>. A host may answer it with 503
/// rather than 401, since the caller did nothing wrong.
/// </summary>
StoreUnavailable,
}
public sealed record ApiKeyIdentity(string KeyId, string DisplayName, IReadOnlySet<string> Scopes, object? Constraints);
@@ -78,3 +106,16 @@ public interface IApiKeyAuditStore
Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken ct);
Task<IReadOnlyList<ApiKeyAuditEntry>> ListRecentAsync(int limit, CancellationToken ct);
}
/// <summary>
/// Creates or upgrades the API-key store schema to the version this build supports. Each store
/// provider (SQLite, SQL Server) supplies one; hosts run it at startup and before admin commands.
/// Implementations must be idempotent and safe to run concurrently from several nodes.
/// </summary>
public interface IApiKeyStoreMigrator
{
/// <summary>Migrates the store schema.</summary>
/// <param name="ct">A token to cancel the operation.</param>
/// <returns>A task that completes when the schema is current.</returns>
Task MigrateAsync(CancellationToken ct);
}
@@ -4,6 +4,20 @@ namespace ZB.MOM.WW.Auth.Abstractions.Ldap;
public enum LdapTransport { Ldaps, StartTls, None }
/// <summary>How <see cref="LdapOptions"/> authenticates a sign-in.</summary>
public enum LdapBindMode
{
/// <summary>Bind as the service account, search for the user, re-bind as the user (0.3.0 behaviour).</summary>
ServiceAccount,
/// <summary>
/// Bind as the signing-in user (identity built from <see cref="LdapOptions.UserBindTemplate"/>);
/// a successful bind authenticates them, and the same connection reads their own entry for groups.
/// No service account is used.
/// </summary>
User,
}
public sealed record LdapOptions
{
public bool Enabled { get; init; } = true;
@@ -19,6 +33,51 @@ public sealed record LdapOptions
public string GroupAttribute { get; init; } = "memberOf";
public int ConnectionTimeoutMs { get; init; } = 10_000;
/// <summary>
/// Selects the authentication flow. <see cref="LdapBindMode.ServiceAccount"/> (the default) is the
/// 0.3.0 bind-then-search-then-bind flow; <see cref="LdapBindMode.User"/> binds as the user and needs
/// no <see cref="ServiceAccountDn"/> / <see cref="ServiceAccountPassword"/>.
/// </summary>
public LdapBindMode BindMode { get; init; } = LdapBindMode.ServiceAccount;
/// <summary>
/// <see cref="LdapBindMode.User"/> only: the simple-bind identity, with <c>{0}</c> replaced by the
/// normalised login name. Must contain <c>{0}</c> exactly once.
/// <para>
/// Prefer the down-level form <c>EXAMPLE\{0}</c>: it maps exactly to the <c>sAMAccountName</c> the
/// group search uses. A UPN template (<c>{0}@example.com</c>) only signs in accounts whose UPN
/// prefix equals their <c>sAMAccountName</c> — AD resolves a UPN bind against the explicit
/// <c>userPrincipalName</c>, so it can bind a different account than the one the search finds.
/// </para>
/// <para>
/// Since 0.4.4 the service proves the entry it reads is the account that bound, and refuses the
/// sign-in (<see cref="LdapAuthFailure.GroupLookupFailed"/>) otherwise. It asks the directory
/// (RFC 4532 "Who am I?") and compares the answer with the entry's DN or, for AD's
/// <c>u:DOMAIN\name</c> answer, its <c>sAMAccountName</c>. A server without Who-am-I (e.g. GLAuth)
/// is only supported with a DN template (containing <c>=</c>), which must produce the entry's DN
/// exactly as the search reports it; <c>{0}</c> is RFC 4514-escaped in a DN template.
/// </para>
/// </summary>
public string UserBindTemplate { get; init; } = "";
/// <summary>
/// <see cref="LdapBindMode.User"/> only: when <see langword="true"/> (default) a login typed as
/// <c>DOMAIN\name</c> or <c>name@suffix</c> is reduced to <c>name</c>; when <see langword="false"/>
/// such input is refused as bad credentials without contacting the directory.
/// </summary>
public bool AcceptDomainQualifiedNames { get; init; } = true;
/// <summary>
/// Ordered fallback LDAP endpoints tried when the primary (and any earlier fallback)
/// fails with a system-side error (connect/TLS, service-account bind, or search).
/// Each entry is <c>"host"</c> (adopts <see cref="Port"/>) or <c>"host:port"</c>.
/// Empty (the default) disables failover entirely — single-endpoint behavior is
/// unchanged. The TLS validation policy (<see cref="ServerCertificateValidationCallback"/>
/// / <see cref="AllowInsecure"/>) applies to every endpoint. Endpoint preference is
/// sticky: the service keeps using the last endpoint that answered until it fails.
/// </summary>
public IReadOnlyList<string> FallbackServers { get; init; } = Array.Empty<string>();
/// <summary>
/// Optional hook to harden (or, in dev, relax) TLS server-certificate validation for the
/// <see cref="LdapTransport.Ldaps"/> / <see cref="LdapTransport.StartTls"/> transports. When
@@ -57,3 +116,80 @@ public interface ILdapAuthService
/// </remarks>
Task<LdapAuthResult> AuthenticateAsync(string username, string password, CancellationToken ct);
}
/// <summary>Outcome of a passwordless <see cref="ILdapGroupLookup.GetUserGroupsAsync"/> call.</summary>
public enum LdapGroupLookupStatus
{
/// <summary>Exactly one entry matched; <see cref="LdapGroupLookupResult.Groups"/> is its group set (may be empty).</summary>
Found,
/// <summary>A healthy directory answered and no entry matched the name — the account was deleted or renamed.</summary>
UserNotFound,
/// <summary>Exactly one entry matched but the directory marks it disabled (AD <c>userAccountControl</c> ACCOUNTDISABLE).</summary>
UserDisabled,
/// <summary>Two or more entries matched; no group set can be attributed to the name.</summary>
AmbiguousUser,
/// <summary>
/// No endpoint gave an answer: connect/TLS, the service-account bind or the search failed on every
/// endpoint (primary and <see cref="LdapOptions.FallbackServers"/>). Says nothing about the user.
/// </summary>
DirectoryUnavailable,
/// <summary>
/// The configuration cannot search without the user's password: <see cref="LdapOptions.BindMode"/> is
/// <see cref="LdapBindMode.User"/> (there is no service account), no
/// <see cref="LdapOptions.ServiceAccountDn"/> is configured, or the registered provider does not implement lookup.
/// </summary>
NotSupported,
/// <summary><see cref="LdapOptions.Enabled"/> is <see langword="false"/>; the network was not touched.</summary>
ProviderDisabled,
}
/// <summary>
/// Result of a passwordless group lookup. <see cref="Username"/>, <see cref="DisplayName"/> and
/// <see cref="Groups"/> are populated only for <see cref="LdapGroupLookupStatus.Found"/>; for every other
/// status they are empty.
/// </summary>
public sealed record LdapGroupLookupResult(
LdapGroupLookupStatus Status,
string Username,
string DisplayName,
IReadOnlyList<string> Groups)
{
/// <summary><see langword="true"/> when <see cref="Status"/> is <see cref="LdapGroupLookupStatus.Found"/>.</summary>
public bool IsFound => Status == LdapGroupLookupStatus.Found;
public static LdapGroupLookupResult Found(string username, string displayName, IReadOnlyList<string> groups)
=> new(LdapGroupLookupStatus.Found, username, displayName, groups);
/// <summary>Any non-<see cref="LdapGroupLookupStatus.Found"/> outcome, with empty identity fields.</summary>
public static LdapGroupLookupResult Of(LdapGroupLookupStatus status)
=> status == LdapGroupLookupStatus.Found
? throw new ArgumentException("Use Found(...) for a successful lookup.", nameof(status))
: new(status, "", "", Array.Empty<string>());
}
/// <summary>
/// Passwordless directory group lookup (since 0.5.0): re-reads a known user's group membership without
/// their credentials, e.g. to refresh an active session's roles when the directory changes.
/// </summary>
public interface ILdapGroupLookup
{
/// <summary>
/// Binds as the configured service account, finds <paramref name="username"/> by
/// <see cref="LdapOptions.UserNameAttribute"/> under <see cref="LdapOptions.SearchBase"/>, and returns the
/// same group set (and canonical username / display name) <see cref="ILdapAuthService.AuthenticateAsync"/>
/// would return for that user in <see cref="LdapBindMode.ServiceAccount"/> mode.
/// </summary>
/// <remarks>
/// Never throws except for cancellation observed at entry; every fault maps to a
/// <see cref="LdapGroupLookupStatus"/>. Endpoint failover, timeouts and TLS policy are the same as
/// <see cref="ILdapAuthService.AuthenticateAsync"/>. Unlike authentication, a <see cref="LdapGroupLookupStatus.Found"/>
/// result may carry zero groups (sign-in would refuse such a user); the caller decides what that means.
/// </remarks>
Task<LdapGroupLookupResult> GetUserGroupsAsync(string username, CancellationToken ct);
}
@@ -11,8 +11,8 @@
<PackageId>ZB.MOM.WW.Auth.Abstractions</PackageId>
<Authors>ZB.MOM.WW</Authors>
<Description>Auth contracts and canonical roles for the ZB.MOM.WW SCADA family.</Description>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-auth</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-auth</RepositoryUrl>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/scadaproj/src/branch/main/ZB.MOM.WW.Auth</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/scadaproj</RepositoryUrl>
</PropertyGroup>
</Project>
@@ -0,0 +1,64 @@
using Microsoft.Data.SqlClient;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer;
/// <summary>
/// Opens connections to the shared SQL Server API-key database and carries the settings every
/// command needs (schema name, command timeout).
/// </summary>
/// <param name="options">The SQL Server API-key store options; validated in the constructor.</param>
/// <exception cref="InvalidOperationException"><paramref name="options"/> is not usable.</exception>
public sealed class AuthSqlServerConnectionFactory(SqlServerApiKeyOptions options)
{
private readonly SqlServerApiKeyOptions _options = Validate(options);
private static SqlServerApiKeyOptions Validate(SqlServerApiKeyOptions options)
{
ArgumentNullException.ThrowIfNull(options);
options.Validate();
return options;
}
/// <summary>The schema that owns the three API-key tables.</summary>
public string Schema => _options.Schema;
/// <summary>Command timeout, in whole seconds, for every command issued against this store.</summary>
public int CommandTimeoutSeconds => Math.Max(1, (int)_options.CommandTimeout.TotalSeconds);
/// <summary>Opens a connection to the shared API-key database.</summary>
/// <param name="cancellationToken">A token to cancel the connect.</param>
/// <returns>An opened connection. The caller owns disposal.</returns>
public async Task<SqlConnection> OpenConnectionAsync(CancellationToken cancellationToken)
{
var connection = new SqlConnection(_options.ConnectionString);
try
{
await connection.OpenAsync(cancellationToken).ConfigureAwait(false);
return connection;
}
catch
{
await connection.DisposeAsync().ConfigureAwait(false);
throw;
}
}
/// <summary>
/// Creates a command on <paramref name="connection"/> with the configured timeout applied.
/// </summary>
/// <param name="connection">The open connection.</param>
/// <param name="commandText">The command text.</param>
/// <param name="transaction">The ambient transaction, if any.</param>
/// <returns>The configured command. The caller owns disposal.</returns>
public SqlCommand CreateCommand(
SqlConnection connection, string commandText, SqlTransaction? transaction = null)
{
ArgumentNullException.ThrowIfNull(connection);
SqlCommand command = connection.CreateCommand();
command.CommandText = commandText;
command.CommandTimeout = CommandTimeoutSeconds;
command.Transaction = transaction;
return command;
}
}
@@ -0,0 +1,96 @@
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Options;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
using ZB.MOM.WW.Auth.ApiKeys.DependencyInjection;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.DependencyInjection;
/// <summary>
/// Dependency-injection entry point that swaps the API-key store backend from the SQLite default
/// to a shared SQL Server database — one row set read and written by every node of a cluster (e.g.
/// a ScadaBridge central pair), instead of the per-node file <see cref="AddZbApiKeyAuth"/> alone
/// would give each node.
/// </summary>
public static class SqlServerApiKeyServiceCollectionExtensions
{
/// <summary>
/// Registers the SQL Server-backed <see cref="IApiKeyStore"/>, <see cref="IApiKeyAdminStore"/>,
/// <see cref="IApiKeyAuditStore"/> and <see cref="IApiKeyStoreMigrator"/>, then calls
/// <see cref="ApiKeyServiceCollectionExtensions.AddZbApiKeyAuth"/> to complete the registration
/// (verifier, pepper provider, migration hosted service).
/// </summary>
/// <remarks>
/// <para>
/// <b>Call this INSTEAD of <see cref="ApiKeyServiceCollectionExtensions.AddZbApiKeyAuth"/></b>,
/// never both — this method calls it internally. The SQL Server stores and migrator are
/// registered here, BEFORE that inner call, precisely because
/// <see cref="ApiKeyServiceCollectionExtensions.AddZbApiKeyAuth"/> registers everything with
/// <c>TryAdd*</c>: whichever implementation of <see cref="IApiKeyStore"/> (etc.) is registered
/// first wins, and a later <c>TryAdd</c> for the same service is a no-op. That ordering is the
/// entire mechanism by which this method displaces the SQLite default.
/// </para>
/// <para>
/// <see cref="ApiKeyServiceCollectionExtensions.AddZbApiKeyAuth"/> still registers a SQLite
/// connection factory from <c>ApiKeyOptions.SqlitePath</c> even when SQL Server wins every
/// store slot. That is harmless — the SQLite factory is lazy and the connection it would open
/// is never opened when nothing resolves it — and it is actually useful: it keeps the one path
/// a node's pre-existing per-node SQLite file lives at in a single option, which is exactly the
/// source path <see cref="SqliteApiKeyStoreImporter"/> needs for the one-shot copy into the
/// shared store.
/// </para>
/// <para>
/// <see cref="SqliteApiKeyStoreImporter"/> is registered here so a host can resolve it and run
/// it once at boot (e.g. from a startup task or its own hosted service) to copy an existing
/// node's per-node keys and audit rows into the now-shared store; it performs no work by being
/// merely registered.
/// </para>
/// <para>
/// <b>The connection string must be a literal value or an environment-variable override — never
/// a <c>${secret:}</c> reference</b> on a host whose secret store is itself SQL-backed: resolving
/// that reference would require a working secret store, which on such a host requires this very
/// database to already be reachable, an unbreakable circular dependency at boot.
/// </para>
/// </remarks>
/// <param name="services">The service collection to add to.</param>
/// <param name="config">The application configuration.</param>
/// <param name="apiKeySectionPath">Path of the configuration section holding the core API-key options.</param>
/// <param name="sqlServerSectionPath">Path of the configuration section holding <see cref="SqlServerApiKeyOptions"/>.</param>
/// <returns>The same <paramref name="services"/> instance, for chaining.</returns>
public static IServiceCollection AddZbApiKeyAuthSqlServer(
this IServiceCollection services,
IConfiguration config,
string apiKeySectionPath,
string sqlServerSectionPath)
{
ArgumentNullException.ThrowIfNull(services);
ArgumentNullException.ThrowIfNull(config);
ArgumentException.ThrowIfNullOrWhiteSpace(apiKeySectionPath);
ArgumentException.ThrowIfNullOrWhiteSpace(sqlServerSectionPath);
services.Configure<SqlServerApiKeyOptions>(config.GetSection(sqlServerSectionPath));
services.TryAddSingleton(sp =>
new AuthSqlServerConnectionFactory(sp.GetRequiredService<IOptions<SqlServerApiKeyOptions>>().Value));
// Registered BEFORE AddZbApiKeyAuth so its TryAdd calls find these already present and
// leave them alone — that is the whole mechanism by which the SQL Server store displaces
// SQLite (see the class remarks).
services.TryAddSingleton<IApiKeyStore>(sp =>
new SqlServerApiKeyStore(sp.GetRequiredService<AuthSqlServerConnectionFactory>()));
services.TryAddSingleton<IApiKeyAdminStore>(sp =>
new SqlServerApiKeyAdminStore(sp.GetRequiredService<AuthSqlServerConnectionFactory>()));
services.TryAddSingleton<IApiKeyAuditStore>(sp =>
new SqlServerApiKeyAuditStore(sp.GetRequiredService<AuthSqlServerConnectionFactory>()));
services.TryAddSingleton<SqlServerApiKeyStoreMigrator>();
services.TryAddSingleton<IApiKeyStoreMigrator>(sp => sp.GetRequiredService<SqlServerApiKeyStoreMigrator>());
// Registered so a host can resolve it and run the one-shot per-node SQLite -> shared store
// copy at boot; registering it here does no work on its own.
services.TryAddSingleton<SqliteApiKeyStoreImporter>();
return services.AddZbApiKeyAuth(config, apiKeySectionPath);
}
}
@@ -0,0 +1,263 @@
using System.Data;
using Microsoft.Data.SqlClient;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer;
/// <summary>
/// SQL Server-backed administration store for API keys (create, revoke, rotate, delete,
/// set-scopes, enable/disable, list).
/// </summary>
/// <remarks>
/// Semantics are a deliberate one-for-one port of <c>SqliteApiKeyAdminStore</c> — same WHERE and SET
/// clauses, same rows-affected return contract — so an admin command behaves identically whichever
/// provider a host composed. The point of this provider is only WHERE the rows live: one shared row
/// set for a clustered pair instead of a file per node, so a revoke on either node is a revoke
/// everywhere.
/// </remarks>
/// <param name="connectionFactory">Factory for connections to the shared API-key database.</param>
public sealed class SqlServerApiKeyAdminStore(AuthSqlServerConnectionFactory connectionFactory) : IApiKeyAdminStore
{
/// <inheritdoc />
/// <remarks>
/// A plain INSERT: a duplicate <c>key_id</c> surfaces as a primary-key
/// <see cref="SqlException"/> rather than silently overwriting an existing key (the SQLite store
/// raises its own <c>SqliteException</c> in the same situation). Unlike SQLite, the primary key
/// follows the database collation, so on a case-insensitive database <c>Line1</c> cannot be
/// created beside <c>line1</c> either. A key id over 64, prefix over 16 or display name over 256
/// characters throws <see cref="ArgumentException"/> before anything is sent (since 0.4.4; it
/// was silently truncated before).
/// </remarks>
/// <exception cref="ArgumentException">A field is longer than its column.</exception>
public async Task CreateAsync(ApiKeyRecord record, CancellationToken ct)
{
ArgumentNullException.ThrowIfNull(record);
SqlServerColumnLimits.EnsureFits(record);
string schema = connectionFactory.Schema;
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
await using SqlCommand command = connectionFactory.CreateCommand(connection, $"""
INSERT INTO [{schema}].[{SqlServerAuthSchema.ApiKeysTable}] (
key_id, key_prefix, secret_hash, display_name, scopes,
constraints, created_utc, last_used_utc, revoked_utc, expires_utc)
VALUES (
@key_id, @key_prefix, @secret_hash, @display_name, @scopes,
@constraints, @created_utc, @last_used_utc, @revoked_utc, @expires_utc);
""");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = record.KeyId;
command.Parameters.Add("@key_prefix", SqlDbType.NVarChar, 16).Value = record.KeyPrefix;
command.Parameters.Add("@secret_hash", SqlDbType.VarBinary, 64).Value = record.SecretHash;
command.Parameters.Add("@display_name", SqlDbType.NVarChar, 256).Value = record.DisplayName;
command.Parameters.Add("@scopes", SqlDbType.NVarChar, -1).Value = ScopeSerializer.Serialize(record.Scopes);
command.Parameters.Add("@constraints", SqlDbType.NVarChar, -1).Value = (object?)record.ConstraintsJson ?? DBNull.Value;
command.Parameters.Add("@created_utc", SqlDbType.DateTimeOffset).Value = record.CreatedUtc;
command.Parameters.Add("@last_used_utc", SqlDbType.DateTimeOffset).Value = (object?)record.LastUsedUtc ?? DBNull.Value;
command.Parameters.Add("@revoked_utc", SqlDbType.DateTimeOffset).Value = (object?)record.RevokedUtc ?? DBNull.Value;
command.Parameters.Add("@expires_utc", SqlDbType.DateTimeOffset).Value = (object?)record.ExpiresUtc ?? DBNull.Value;
await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
}
/// <inheritdoc />
/// <remarks>
/// Guarded on <c>revoked_utc IS NULL</c>, so the returned flag means "this call revoked it" —
/// a second revoke of the same key returns <see langword="false"/> and preserves the original
/// revocation instant.
/// </remarks>
public async Task<bool> RevokeAsync(string keyId, DateTimeOffset whenUtc, CancellationToken ct)
{
ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
if (!SqlServerColumnLimits.CanExist(keyId))
return false;
string schema = connectionFactory.Schema;
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
await using SqlCommand command = connectionFactory.CreateCommand(connection, $"""
UPDATE [{schema}].[{SqlServerAuthSchema.ApiKeysTable}]
SET revoked_utc = @revoked_utc
WHERE key_id = @key_id AND {SqlServerColumnLimits.ExactKeyIdMatch} AND revoked_utc IS NULL;
""");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = keyId;
command.Parameters.Add("@revoked_utc", SqlDbType.DateTimeOffset).Value = whenUtc;
int rows = await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
return rows > 0;
}
/// <inheritdoc />
/// <remarks>
/// Rotating also clears <c>last_used_utc</c> and <c>revoked_utc</c> — a rotated key is a fresh,
/// active credential — while leaving <c>expires_utc</c> alone, so an absolute expiry survives a
/// rotation.
/// </remarks>
public async Task<bool> RotateAsync(string keyId, byte[] newSecretHash, CancellationToken ct)
{
ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
if (!SqlServerColumnLimits.CanExist(keyId))
return false;
ArgumentNullException.ThrowIfNull(newSecretHash);
string schema = connectionFactory.Schema;
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
await using SqlCommand command = connectionFactory.CreateCommand(connection, $"""
UPDATE [{schema}].[{SqlServerAuthSchema.ApiKeysTable}]
SET secret_hash = @secret_hash,
last_used_utc = NULL,
revoked_utc = NULL
WHERE key_id = @key_id AND {SqlServerColumnLimits.ExactKeyIdMatch};
""");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = keyId;
command.Parameters.Add("@secret_hash", SqlDbType.VarBinary, 64).Value = newSecretHash;
int rows = await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
return rows > 0;
}
/// <inheritdoc />
public async Task<bool> SetScopesAsync(string keyId, IReadOnlySet<string> scopes, CancellationToken ct)
{
ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
if (!SqlServerColumnLimits.CanExist(keyId))
return false;
ArgumentNullException.ThrowIfNull(scopes);
string schema = connectionFactory.Schema;
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
await using SqlCommand command = connectionFactory.CreateCommand(connection, $"""
UPDATE [{schema}].[{SqlServerAuthSchema.ApiKeysTable}]
SET scopes = @scopes
WHERE key_id = @key_id AND {SqlServerColumnLimits.ExactKeyIdMatch};
""");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = keyId;
command.Parameters.Add("@scopes", SqlDbType.NVarChar, -1).Value = ScopeSerializer.Serialize(scopes);
int rows = await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
return rows > 0;
}
/// <inheritdoc />
public async Task<bool> SetEnabledAsync(string keyId, bool enabled, DateTimeOffset whenUtc, CancellationToken ct)
{
ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
if (!SqlServerColumnLimits.CanExist(keyId))
return false;
string schema = connectionFactory.Schema;
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
// Reversible toggle: NO `revoked_utc IS NULL` guard (unlike RevokeAsync), so it works
// regardless of current state. Deliberately leaves secret_hash and last_used_utc untouched
// — that is what distinguishes re-enable from RotateAsync.
SqlCommand command;
if (enabled)
{
command = connectionFactory.CreateCommand(connection, $"""
UPDATE [{schema}].[{SqlServerAuthSchema.ApiKeysTable}]
SET revoked_utc = NULL
WHERE key_id = @key_id AND {SqlServerColumnLimits.ExactKeyIdMatch};
""");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = keyId;
}
else
{
command = connectionFactory.CreateCommand(connection, $"""
UPDATE [{schema}].[{SqlServerAuthSchema.ApiKeysTable}]
SET revoked_utc = @revoked_utc
WHERE key_id = @key_id AND {SqlServerColumnLimits.ExactKeyIdMatch};
""");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = keyId;
command.Parameters.Add("@revoked_utc", SqlDbType.DateTimeOffset).Value = whenUtc;
}
await using (command)
{
int rows = await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
return rows > 0;
}
}
/// <inheritdoc />
/// <remarks>
/// Only a REVOKED key can be deleted (<c>revoked_utc IS NOT NULL</c>), so an active credential
/// cannot vanish in one step — revoke first, and the revocation stands on its own until then.
/// </remarks>
public async Task<bool> DeleteAsync(string keyId, CancellationToken ct)
{
ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
if (!SqlServerColumnLimits.CanExist(keyId))
return false;
string schema = connectionFactory.Schema;
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
await using SqlCommand command = connectionFactory.CreateCommand(connection, $"""
DELETE FROM [{schema}].[{SqlServerAuthSchema.ApiKeysTable}]
WHERE key_id = @key_id AND {SqlServerColumnLimits.ExactKeyIdMatch} AND revoked_utc IS NOT NULL;
""");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = keyId;
int rows = await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
return rows > 0;
}
/// <inheritdoc />
public async Task<IReadOnlyList<ApiKeyListItem>> ListAsync(CancellationToken ct)
{
string schema = connectionFactory.Schema;
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
// Deliberately omits secret_hash so listing can never leak secret material. key_id is the
// tie-break so keys minted in the same instant still list in a stable order.
await using SqlCommand command = connectionFactory.CreateCommand(connection, $"""
SELECT key_id, key_prefix, display_name, scopes, constraints,
created_utc, last_used_utc, revoked_utc, expires_utc
FROM [{schema}].[{SqlServerAuthSchema.ApiKeysTable}]
ORDER BY created_utc DESC, key_id DESC;
""");
List<ApiKeyListItem> items = [];
await using SqlDataReader reader = await command.ExecuteReaderAsync(ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
items.Add(new ApiKeyListItem(
KeyId: reader.GetString(0),
KeyPrefix: reader.GetString(1),
DisplayName: reader.GetString(2),
Scopes: ScopeSerializer.Deserialize(reader.GetString(3)),
ConstraintsJson: reader.IsDBNull(4) ? null : reader.GetString(4),
CreatedUtc: reader.GetDateTimeOffset(5),
LastUsedUtc: reader.IsDBNull(6) ? null : reader.GetDateTimeOffset(6),
RevokedUtc: reader.IsDBNull(7) ? null : reader.GetDateTimeOffset(7),
ExpiresUtc: reader.IsDBNull(8) ? null : reader.GetDateTimeOffset(8)));
}
return items;
}
}
@@ -0,0 +1,88 @@
using System.Data;
using Microsoft.Data.SqlClient;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer;
/// <summary>
/// SQL Server-backed, append-only audit store for API-key events. A one-for-one port of
/// <c>SqliteApiKeyAuditStore</c>; on a clustered host the rows from every node land in one table,
/// so the audit trail no longer has to be stitched together per node.
/// </summary>
/// <param name="connectionFactory">Factory for connections to the shared API-key database.</param>
public sealed class SqlServerApiKeyAuditStore(AuthSqlServerConnectionFactory connectionFactory) : IApiKeyAuditStore
{
/// <inheritdoc />
/// <remarks>
/// <b>Over-length text is truncated, deliberately.</b> <c>key_id</c>, <c>event_type</c> and
/// <c>remote_address</c> are 64-character columns; a longer value is stored as its first 64
/// characters (the SQLite store keeps it whole). Unlike a key record (refused when over-length,
/// see <see cref="SqlServerApiKeyAdminStore.CreateAsync"/>), an audit append is not refused: it
/// runs after the action it records, and failing it would lose the record of a change that has
/// already happened. <c>details</c> is unbounded.
/// </remarks>
public async Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken ct)
{
ArgumentNullException.ThrowIfNull(entry);
string schema = connectionFactory.Schema;
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
await using SqlCommand command = connectionFactory.CreateCommand(connection, $"""
INSERT INTO [{schema}].[{SqlServerAuthSchema.ApiKeyAuditTable}] (
key_id, event_type, remote_address, created_utc, details)
VALUES (@key_id, @event_type, @remote_address, @created_utc, @details);
""");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = (object?)entry.KeyId ?? DBNull.Value;
command.Parameters.Add("@event_type", SqlDbType.NVarChar, 64).Value = entry.EventType;
command.Parameters.Add("@remote_address", SqlDbType.NVarChar, 64).Value = (object?)entry.RemoteAddress ?? DBNull.Value;
command.Parameters.Add("@created_utc", SqlDbType.DateTimeOffset).Value = entry.CreatedUtc;
command.Parameters.Add("@details", SqlDbType.NVarChar, -1).Value = (object?)entry.Details ?? DBNull.Value;
await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
}
/// <inheritdoc />
/// <remarks>
/// Ordered by the IDENTITY <c>audit_id</c>, not by <c>created_utc</c>: two events stamped in the
/// same instant still come back in insertion order. A non-positive limit short-circuits without
/// opening a connection — <c>SELECT TOP (-1)</c> is not even legal T-SQL.
/// </remarks>
public async Task<IReadOnlyList<ApiKeyAuditEntry>> ListRecentAsync(int limit, CancellationToken ct)
{
if (limit <= 0)
{
return [];
}
string schema = connectionFactory.Schema;
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
await using SqlCommand command = connectionFactory.CreateCommand(connection, $"""
SELECT TOP (@limit) key_id, event_type, remote_address, created_utc, details
FROM [{schema}].[{SqlServerAuthSchema.ApiKeyAuditTable}]
ORDER BY audit_id DESC;
""");
command.Parameters.Add("@limit", SqlDbType.Int).Value = limit;
List<ApiKeyAuditEntry> entries = [];
await using SqlDataReader reader = await command.ExecuteReaderAsync(ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
entries.Add(new ApiKeyAuditEntry(
KeyId: reader.IsDBNull(0) ? null : reader.GetString(0),
EventType: reader.GetString(1),
RemoteAddress: reader.IsDBNull(2) ? null : reader.GetString(2),
CreatedUtc: reader.GetDateTimeOffset(3),
Details: reader.IsDBNull(4) ? null : reader.GetString(4)));
}
return entries;
}
}
@@ -0,0 +1,65 @@
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer;
/// <summary>
/// Options for the shared SQL Server API-key store (section supplied by the host, e.g.
/// <c>ScadaBridge:InboundApi:ApiKeyStore:SqlServer</c>).
/// </summary>
public sealed class SqlServerApiKeyOptions
{
/// <summary>
/// Full SQL Server connection string. Required. Never a <c>${secret:}</c> reference on hosts
/// whose secret store is itself SQL-backed.
/// </summary>
public string ConnectionString { get; set; } = string.Empty;
/// <summary>Schema that owns the three tables. Letters, digits and underscore only (it is interpolated into DDL).</summary>
public string Schema { get; set; } = "zbauth";
/// <summary>
/// Command timeout applied to every store operation. Defaults to 30 seconds — long enough for
/// a contended shared database, short enough that a hung server surfaces as an error rather
/// than stalling a resolve indefinitely.
/// </summary>
public TimeSpan CommandTimeout { get; set; } = TimeSpan.FromSeconds(30);
/// <summary>Fails fast on a blank connection string, an unsafe schema identifier, or a non-positive command timeout.</summary>
/// <exception cref="InvalidOperationException">The options are not usable.</exception>
public void Validate()
{
if (string.IsNullOrWhiteSpace(ConnectionString))
throw new InvalidOperationException("SQL Server API-key store requires a ConnectionString.");
ValidateIdentifier(Schema);
if (CommandTimeout <= TimeSpan.Zero)
throw new InvalidOperationException($"SQL Server API-key store CommandTimeout must be positive (was {CommandTimeout}).");
}
/// <summary>
/// Strict allow-list for a SQL identifier that will be interpolated into DDL or query text.
/// Rejects everything that is not <c>[A-Za-z_][A-Za-z0-9_]{0,63}</c> — no brackets, quotes, dots
/// or spaces — so no bracket-escape (<c>]]</c>) trick can break out of the quoting applied at the
/// use site. Uses the ASCII-only character tests deliberately, so homoglyph and full-width
/// look-alikes are rejected rather than accepted as "letters".
/// </summary>
/// <param name="schemaName">The candidate identifier.</param>
/// <returns>The same value, once validated.</returns>
/// <exception cref="InvalidOperationException">The value is not a plain identifier.</exception>
/// <remarks>
/// Public because <see cref="SqlServerAuthSchema.CreateSchemaDdl(string)"/> is public and must
/// defend itself rather than trust that every caller routed through <see cref="Validate"/>.
/// </remarks>
public static string ValidateIdentifier(string schemaName)
{
if (string.IsNullOrEmpty(schemaName)
|| schemaName.Length > 64
|| (!char.IsAsciiLetter(schemaName[0]) && schemaName[0] != '_')
|| !schemaName.All(c => char.IsAsciiLetterOrDigit(c) || c == '_'))
{
throw new InvalidOperationException(
$"SQL Server API-key store schema name '{schemaName}' is not a safe identifier.");
}
return schemaName;
}
}
@@ -0,0 +1,107 @@
using System.Data;
using Microsoft.Data.SqlClient;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer;
/// <summary>
/// SQL Server-backed read store for API-key records — the verification hot path.
/// </summary>
/// <remarks>
/// Semantics are a deliberate one-for-one port of <c>SqliteApiKeyStore</c>, down to the WHERE
/// clauses, so a host can switch providers without any behaviour changing. One connection per
/// operation: the shared store is reached over the network and pooling, not a held connection, is
/// what keeps a central pair's concurrent verifies cheap.
/// </remarks>
/// <param name="connectionFactory">Factory for connections to the shared API-key database.</param>
public sealed class SqlServerApiKeyStore(AuthSqlServerConnectionFactory connectionFactory) : IApiKeyStore
{
private const string SelectColumns =
"key_id, key_prefix, secret_hash, display_name, scopes, constraints, created_utc, last_used_utc, revoked_utc, expires_utc";
/// <inheritdoc />
public Task<ApiKeyRecord?> FindByKeyIdAsync(string keyId, CancellationToken ct)
{
ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
return FindAsync(keyId, requireActive: false, ct);
}
/// <inheritdoc />
public Task<ApiKeyRecord?> FindActiveByKeyIdAsync(string keyId, CancellationToken ct)
{
ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
return FindAsync(keyId, requireActive: true, ct);
}
/// <inheritdoc />
/// <remarks>
/// Guarded on <c>revoked_utc IS NULL</c>: a revoked key's last-used stamp is frozen at its last
/// legitimate use, so it never records the rejected attempts that follow.
/// </remarks>
public async Task MarkUsedAsync(string keyId, DateTimeOffset whenUtc, CancellationToken ct)
{
ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
if (!SqlServerColumnLimits.CanExist(keyId))
return;
string schema = connectionFactory.Schema;
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
await using SqlCommand command = connectionFactory.CreateCommand(connection, $"""
UPDATE [{schema}].[{SqlServerAuthSchema.ApiKeysTable}]
SET last_used_utc = @last_used_utc
WHERE key_id = @key_id AND {SqlServerColumnLimits.ExactKeyIdMatch} AND revoked_utc IS NULL;
""");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = keyId;
command.Parameters.Add("@last_used_utc", SqlDbType.DateTimeOffset).Value = whenUtc;
await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
}
private async Task<ApiKeyRecord?> FindAsync(string keyId, bool requireActive, CancellationToken ct)
{
// An id longer than the column cannot be stored; querying would truncate it and could match
// another key sharing its first 64 characters (Auth-008).
if (!SqlServerColumnLimits.CanExist(keyId))
return null;
string schema = connectionFactory.Schema;
string table = $"[{schema}].[{SqlServerAuthSchema.ApiKeysTable}]";
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
// Active means NOT REVOKED only. Expiry is deliberately not filtered here — the verifier
// owns it, so it can tell an expired key from an unknown one (ApiKeyFailure.KeyExpired).
await using SqlCommand command = connectionFactory.CreateCommand(
connection,
requireActive
? $"SELECT {SelectColumns} FROM {table} WHERE key_id = @key_id AND {SqlServerColumnLimits.ExactKeyIdMatch} AND revoked_utc IS NULL;"
: $"SELECT {SelectColumns} FROM {table} WHERE key_id = @key_id AND {SqlServerColumnLimits.ExactKeyIdMatch};");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = keyId;
await using SqlDataReader reader = await command.ExecuteReaderAsync(ct).ConfigureAwait(false);
if (!await reader.ReadAsync(ct).ConfigureAwait(false))
{
return null;
}
return ReadRecord(reader);
}
internal static ApiKeyRecord ReadRecord(SqlDataReader reader) => new(
KeyId: reader.GetString(0),
KeyPrefix: reader.GetString(1),
SecretHash: reader.GetFieldValue<byte[]>(2),
DisplayName: reader.GetString(3),
Scopes: ScopeSerializer.Deserialize(reader.GetString(4)),
ConstraintsJson: reader.IsDBNull(5) ? null : reader.GetString(5),
CreatedUtc: reader.GetDateTimeOffset(6),
LastUsedUtc: reader.IsDBNull(7) ? null : reader.GetDateTimeOffset(7),
RevokedUtc: reader.IsDBNull(8) ? null : reader.GetDateTimeOffset(8),
ExpiresUtc: reader.IsDBNull(9) ? null : reader.GetDateTimeOffset(9));
}
@@ -0,0 +1,207 @@
using System.Data;
using System.Globalization;
using Microsoft.Data.SqlClient;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer;
/// <summary>
/// Creates the shared SQL Server API-key schema and records the applied version. Idempotent: safe
/// to run on every node at every startup, including concurrently — lost provisioning races surface
/// as retryable <see cref="SqlException"/>s (see <see cref="IsRetryableMigrationErrorNumber"/>) and
/// the retry re-runs the <c>IF NOT EXISTS</c> path against the objects the winner just created.
/// Refuses to run against a database whose recorded version is newer than this build supports.
/// </summary>
/// <param name="connectionFactory">Factory for connections to the shared API-key database.</param>
public sealed class SqlServerApiKeyStoreMigrator(AuthSqlServerConnectionFactory connectionFactory)
: IApiKeyStoreMigrator
{
// Every node runs this at every startup, so a virgin database being provisioned by N nodes at
// once is the NORMAL case, not a rare race — and an unretried failure aborts that node's whole
// host at startup. Two failure shapes come out of that race, and retrying is correct for both
// precisely because the migration is idempotent:
//
// - Deadlock victim (1205): concurrent Serializable DDL against the system catalogs can pick
// a victim even though the IF NOT EXISTS guards make the logic itself safe.
// - Lost CREATE / lost INSERT (2714, 1913, 2627): Serializable range locks do NOT serialize
// the metadata existence checks against another session's in-flight CREATE — observed live
// on the sibling shared secret store (ScadaBridge central-pair first boot, 2026-08-07):
// both nodes passed the sys.schemas IF NOT EXISTS probe, the loser's CREATE SCHEMA then
// died with 2714 "There is already an object named 'zbsecrets'". The object the loser tried
// to create now exists, which is the desired end state — the retry's IF NOT EXISTS pass
// skips it and proceeds.
//
// The retry cap keeps this from masking a GENUINE conflict (e.g. an unrelated pre-existing
// object colliding with the schema name): that reproduces on every attempt, so after
// MaxMigrationRetries the real SqlException propagates and the node fails closed.
private const int MaxMigrationRetries = 5;
/// <summary>Deadlock victim.</summary>
private const int SqlDeadlockVictimErrorNumber = 1205;
/// <summary>"There is already an object named '%ls'" — lost CREATE SCHEMA / CREATE TABLE race.</summary>
private const int SqlObjectAlreadyExistsErrorNumber = 2714;
/// <summary>"An index or statistics with name '%ls' already exists" — lost CREATE INDEX race.</summary>
private const int SqlIndexAlreadyExistsErrorNumber = 1913;
/// <summary>Primary-key violation — lost version-row MERGE-insert race.</summary>
private const int SqlPrimaryKeyViolationErrorNumber = 2627;
/// <inheritdoc />
/// <exception cref="AuthStoreMigrationException">
/// The recorded schema version is newer than <see cref="SqlServerAuthSchema.CurrentVersion"/>.
/// </exception>
public async Task MigrateAsync(CancellationToken cancellationToken)
{
for (int attempt = 1; ; attempt++)
{
try
{
await MigrateOnceAsync(cancellationToken).ConfigureAwait(false);
return;
}
catch (SqlException ex)
when (IsRetryableMigrationError(ex) && attempt < MaxMigrationRetries)
{
await Task.Delay(BackoffFor(attempt), cancellationToken).ConfigureAwait(false);
}
}
}
/// <summary>
/// Back-off before retry attempt <paramref name="attempt"/> + 1: a growing base plus RANDOM
/// jitter. The jitter is the load-bearing half. The sibling secret-store migrator this is ported
/// from delays a flat <c>100 * attempt</c>, which is the SAME value for every victim of the same
/// round — so N deadlock victims wake together and re-collide, exactly the lockstep its comment
/// claims to prevent. Measured here against a live SQL Server with eight concurrent migrators on
/// a virgin schema, the unjittered form exhausted the five-attempt budget on repeated 1205s in
/// roughly 1 run in 60; with jitter it did not.
/// </summary>
/// <param name="attempt">The 1-based attempt that just failed.</param>
/// <returns>How long to wait before the next attempt.</returns>
private static TimeSpan BackoffFor(int attempt) =>
TimeSpan.FromMilliseconds((100 * attempt) + Random.Shared.Next(0, 100 * attempt));
/// <summary>
/// Whether any error carried by <paramref name="exception"/> is a retryable provisioning-race
/// outcome. Scans the whole <see cref="SqlException.Errors"/> collection rather than only
/// <see cref="SqlException.Number"/> because a failed DDL batch stacks follow-on errors (e.g.
/// 2714 arrives with 2759 "CREATE SCHEMA failed due to previous errors") and the retryable one
/// is not guaranteed to be first.
/// </summary>
/// <param name="exception">The exception the migration attempt failed with.</param>
/// <returns><see langword="true"/> when a retry may succeed.</returns>
internal static bool IsRetryableMigrationError(SqlException exception)
{
foreach (SqlError error in exception.Errors)
{
if (IsRetryableMigrationErrorNumber(error.Number))
{
return true;
}
}
return IsRetryableMigrationErrorNumber(exception.Number);
}
/// <summary>
/// Classifies a SQL Server error number as a retryable outcome of N nodes provisioning the same
/// (possibly virgin) database at once. Everything here is a race whose retry re-runs the
/// idempotent <c>IF NOT EXISTS</c> path; anything else (login failures, missing database,
/// permissions, syntax) reproduces identically on retry and must propagate. 2705 (duplicate
/// column) is deliberately absent: every column lives inside a single <c>CREATE TABLE</c>
/// statement, so no cross-session race can produce it.
/// </summary>
/// <param name="errorNumber">The <see cref="SqlError.Number"/> to classify.</param>
/// <returns><see langword="true"/> when the number is a known provisioning-race outcome.</returns>
internal static bool IsRetryableMigrationErrorNumber(int errorNumber) => errorNumber
is SqlDeadlockVictimErrorNumber
or SqlObjectAlreadyExistsErrorNumber
or SqlIndexAlreadyExistsErrorNumber
or SqlPrimaryKeyViolationErrorNumber;
private async Task MigrateOnceAsync(CancellationToken cancellationToken)
{
string schema = connectionFactory.Schema;
await using SqlConnection connection =
await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
// Serializable: unlike the single-writer SQLite store, EVERY node in the cluster runs this
// migration at startup, so concurrent first-boots are the normal case rather than a rare
// race. The isolation level narrows the race window but does NOT close it — the IF NOT
// EXISTS metadata probes are not serialized against another session's in-flight CREATE, so
// a loser can still fail with "object exists" (2714/1913) or a deadlock (1205). The retry
// filter in MigrateAsync is what makes simultaneous provision converge: by the time the
// loser retries, the winner's objects exist and every guard here skips them.
await using SqlTransaction transaction = (SqlTransaction)
await connection.BeginTransactionAsync(IsolationLevel.Serializable, cancellationToken)
.ConfigureAwait(false);
int existingVersion =
await ReadExistingSchemaVersionAsync(connection, transaction, schema, cancellationToken)
.ConfigureAwait(false);
if (existingVersion > SqlServerAuthSchema.CurrentVersion)
{
throw new AuthStoreMigrationException(
$"Shared API-key database schema version {existingVersion} is newer than supported version " +
$"{SqlServerAuthSchema.CurrentVersion}. Upgrade this node before it writes to the shared store.");
}
await using (SqlCommand ddl = connectionFactory.CreateCommand(
connection, SqlServerAuthSchema.CreateSchemaDdl(schema), transaction))
{
await ddl.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
}
// MERGE rather than insert-if-missing: WHEN MATCHED re-stamps the row, so a future schema
// version actually lands in the table instead of leaving the first-ever value behind.
await using (SqlCommand version = connectionFactory.CreateCommand(
connection,
$"""
MERGE [{schema}].[{SqlServerAuthSchema.SchemaVersionTable}] AS target
USING (SELECT 1 AS id, @version AS version, @applied_utc AS applied_utc) AS source
ON target.id = source.id
WHEN MATCHED THEN
UPDATE SET version = source.version, applied_utc = source.applied_utc
WHEN NOT MATCHED THEN
INSERT (id, version, applied_utc) VALUES (1, source.version, source.applied_utc);
""",
transaction))
{
version.Parameters.Add("@version", SqlDbType.Int).Value = SqlServerAuthSchema.CurrentVersion;
version.Parameters.Add("@applied_utc", SqlDbType.DateTimeOffset).Value = DateTimeOffset.UtcNow;
await version.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
}
await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
}
private async Task<int> ReadExistingSchemaVersionAsync(
SqlConnection connection,
SqlTransaction transaction,
string schema,
CancellationToken cancellationToken)
{
// OBJECT_ID returns NULL for an absent table, so this reads 0 on a virgin database without
// needing the table to exist first.
await using SqlCommand command = connectionFactory.CreateCommand(
connection,
$"""
IF OBJECT_ID(N'[{schema}].[{SqlServerAuthSchema.SchemaVersionTable}]', N'U') IS NULL
SELECT 0;
ELSE
SELECT ISNULL((SELECT version FROM [{schema}].[{SqlServerAuthSchema.SchemaVersionTable}] WHERE id = 1), 0);
""",
transaction);
object? version = await command.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false);
return version is null || version == DBNull.Value
? 0
: Convert.ToInt32(version, CultureInfo.InvariantCulture);
}
}
@@ -0,0 +1,116 @@
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer;
/// <summary>
/// Schema constants and DDL for the shared SQL Server API-key store. Mirrors
/// <c>ZB.MOM.WW.Auth.ApiKeys.Sqlite.SqliteAuthSchema</c> column-for-column so a row means exactly
/// the same thing in either store.
/// </summary>
/// <remarks>
/// <para>
/// <b>Timestamps are <c>DATETIMEOFFSET(7)</c>, not ISO-8601 text.</b> The sibling
/// <c>ZB.MOM.WW.Secrets</c> SQL Server store deliberately stores its timestamps as
/// <c>nvarchar</c> because its rows <em>replicate</em> with a SQLite store and last-writer-wins
/// compares those timestamps for equality, where a sub-tick round-trip difference would turn a tie
/// into a spurious "newer". No such rationale applies here: this store never replicates with the
/// SQLite one — a host picks exactly one provider, and the one-shot SQLite import is a copy, not an
/// ongoing sync — so the native type is used, which sorts and range-scans correctly and keeps the
/// tables readable to a DBA.
/// </para>
/// <para>
/// <c>SqliteAuthSchema.CurrentVersion</c> is 3 only because that store carries the donor
/// MxAccessGateway's version history (v1/v2 were byte-identical; v3 added <c>expires_utc</c>). This
/// schema is created whole, with <c>expires_utc</c> present from the start, so its own version line
/// starts at 1.
/// </para>
/// </remarks>
public static class SqlServerAuthSchema
{
/// <summary>
/// The schema version this build creates and supports. The migrator refuses a database whose
/// recorded version is <em>newer</em> than this.
/// </summary>
public const int CurrentVersion = 1;
/// <summary>Default schema the API-key tables live in.</summary>
public const string DefaultSchemaName = "zbauth";
/// <summary>Name of the single-row table tracking the applied schema version.</summary>
public const string SchemaVersionTable = "schema_version";
/// <summary>Name of the table storing API-key records.</summary>
public const string ApiKeysTable = "api_keys";
/// <summary>Name of the append-only audit table.</summary>
public const string ApiKeyAuditTable = "api_key_audit";
/// <summary>
/// Returns the idempotent DDL that provisions the schema, the three tables and the two
/// supporting indexes in <paramref name="schemaName"/>.
/// </summary>
/// <param name="schemaName">The SQL schema name to create the objects in.</param>
/// <returns>The DDL batch.</returns>
/// <remarks>
/// <paramref name="schemaName"/> is interpolated, not parameterized — T-SQL has no parameter
/// form for an object name. It is re-validated here against the same strict identifier
/// allow-list <see cref="SqlServerApiKeyOptions.Validate"/> enforces, and bracket-quoted below.
/// The duplicate check is deliberate: this method is <c>public</c>, so it must defend itself
/// rather than trust that every caller routed through the options type. The version row is NOT
/// written here — <see cref="SqlServerApiKeyStoreMigrator"/> writes it with a MERGE that also
/// updates on match, so a future upgrade re-stamps the stored version.
/// </remarks>
/// <exception cref="InvalidOperationException"><paramref name="schemaName"/> is not a plain identifier.</exception>
public static string CreateSchemaDdl(string schemaName)
{
SqlServerApiKeyOptions.ValidateIdentifier(schemaName);
return $"""
IF NOT EXISTS (SELECT 1 FROM sys.schemas WHERE name = N'{schemaName}')
EXEC(N'CREATE SCHEMA [{schemaName}]');
IF OBJECT_ID(N'[{schemaName}].[{SchemaVersionTable}]', N'U') IS NULL
CREATE TABLE [{schemaName}].[{SchemaVersionTable}] (
id INT NOT NULL CONSTRAINT PK_{schemaName}_{SchemaVersionTable} PRIMARY KEY CHECK (id = 1),
version INT NOT NULL,
applied_utc DATETIMEOFFSET(7) NOT NULL
);
IF OBJECT_ID(N'[{schemaName}].[{ApiKeysTable}]', N'U') IS NULL
CREATE TABLE [{schemaName}].[{ApiKeysTable}] (
key_id NVARCHAR(64) NOT NULL CONSTRAINT PK_{schemaName}_{ApiKeysTable} PRIMARY KEY,
key_prefix NVARCHAR(16) NOT NULL,
secret_hash VARBINARY(64) NOT NULL,
display_name NVARCHAR(256) NOT NULL,
scopes NVARCHAR(MAX) NOT NULL,
constraints NVARCHAR(MAX) NULL,
created_utc DATETIMEOFFSET(7) NOT NULL,
last_used_utc DATETIMEOFFSET(7) NULL,
revoked_utc DATETIMEOFFSET(7) NULL,
expires_utc DATETIMEOFFSET(7) NULL
);
IF OBJECT_ID(N'[{schemaName}].[{ApiKeyAuditTable}]', N'U') IS NULL
CREATE TABLE [{schemaName}].[{ApiKeyAuditTable}] (
audit_id BIGINT IDENTITY(1,1) NOT NULL CONSTRAINT PK_{schemaName}_{ApiKeyAuditTable} PRIMARY KEY,
key_id NVARCHAR(64) NULL,
event_type NVARCHAR(64) NOT NULL,
remote_address NVARCHAR(64) NULL,
created_utc DATETIMEOFFSET(7) NOT NULL,
details NVARCHAR(MAX) NULL
);
IF NOT EXISTS (
SELECT 1 FROM sys.indexes
WHERE name = N'ix_api_keys_revoked_utc'
AND object_id = OBJECT_ID(N'[{schemaName}].[{ApiKeysTable}]'))
CREATE INDEX ix_api_keys_revoked_utc
ON [{schemaName}].[{ApiKeysTable}] (revoked_utc);
IF NOT EXISTS (
SELECT 1 FROM sys.indexes
WHERE name = N'ix_api_key_audit_key_id_created_utc'
AND object_id = OBJECT_ID(N'[{schemaName}].[{ApiKeyAuditTable}]'))
CREATE INDEX ix_api_key_audit_key_id_created_utc
ON [{schemaName}].[{ApiKeyAuditTable}] (key_id, created_utc);
""";
}
}
@@ -0,0 +1,61 @@
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer;
/// <summary>
/// Keeps the SQL Server stores' key-id handling identical to the SQLite store they port (Auth-008):
/// no silent truncation and exact key-id matching.
/// </summary>
/// <remarks>
/// <para>
/// <b>Lengths.</b> Every parameter carries an explicit size, and SqlClient truncates an over-length
/// value to that size without an error. So an over-length key record is refused up front, and a
/// lookup of an over-length key id answers "not found" without querying — such a key cannot exist,
/// and the truncated parameter would otherwise match a different key that shares its first 64
/// characters.
/// </para>
/// <para>
/// <b>Case.</b> The <c>key_id</c> column uses the database's collation, case-insensitive on a stock
/// SQL Server, whereas SQLite compares key ids byte-for-byte. Changing the column's collation would
/// need a schema migration of a primary key on a live shared store, so every <c>key_id</c> predicate
/// instead adds <see cref="ExactKeyIdMatch"/>: the collation-aware <c>=</c> still drives the primary-key
/// seek, and the binary comparison then rejects a row that differs in case or trailing spaces.
/// </para>
/// </remarks>
internal static class SqlServerColumnLimits
{
/// <summary>Width of <c>api_keys.key_id</c> (and <c>api_key_audit.key_id</c>).</summary>
public const int KeyId = 64;
/// <summary>Width of <c>api_keys.key_prefix</c>.</summary>
public const int KeyPrefix = 16;
/// <summary>Width of <c>api_keys.display_name</c>.</summary>
public const int DisplayName = 256;
/// <summary>
/// Appended to every <c>key_id = @key_id</c>. <c>NVARCHAR</c> → <c>VARBINARY</c> yields the UTF-16
/// bytes, so the comparison is exact (case, accents and trailing spaces all significant).
/// </summary>
public const string ExactKeyIdMatch = "CAST(key_id AS VARBINARY(128)) = CAST(@key_id AS VARBINARY(128))";
/// <summary>Whether a key with this id could be stored at all.</summary>
public static bool CanExist(string keyId) => keyId.Length <= KeyId;
/// <summary>The first over-length field of <paramref name="record"/>, described, or <see langword="null"/> when every field fits.</summary>
public static string? OverLengthField(ApiKeyRecord record) =>
record.KeyId.Length > KeyId ? Describe(nameof(ApiKeyRecord.KeyId), record.KeyId.Length, KeyId)
: record.KeyPrefix.Length > KeyPrefix ? Describe(nameof(ApiKeyRecord.KeyPrefix), record.KeyPrefix.Length, KeyPrefix)
: record.DisplayName.Length > DisplayName ? Describe(nameof(ApiKeyRecord.DisplayName), record.DisplayName.Length, DisplayName)
: null;
/// <summary>Throws <see cref="ArgumentException"/> when a field of <paramref name="record"/> exceeds its column.</summary>
public static void EnsureFits(ApiKeyRecord record)
{
if (OverLengthField(record) is { } problem)
throw new ArgumentException($"API key record cannot be stored in SQL Server: {problem}.", nameof(record));
}
private static string Describe(string field, int length, int max) =>
$"{field} is {length} characters, more than the column's {max}";
}
@@ -0,0 +1,361 @@
using System.Data;
using Microsoft.Data.SqlClient;
using Microsoft.Data.Sqlite;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer;
/// <summary>Result of a one-shot import.</summary>
/// <param name="KeysInserted">Keys copied into SQL Server by this run.</param>
/// <param name="KeysSkipped">Keys whose <c>key_id</c> already existed in SQL Server.</param>
/// <param name="AuditInserted">Audit rows copied into SQL Server by this run.</param>
/// <param name="AuditSkipped">Audit rows that already existed in SQL Server.</param>
/// <param name="SourceFound">Whether the SQLite file existed at all.</param>
public sealed record ApiKeyImportResult(
int KeysInserted, int KeysSkipped, int AuditInserted, int AuditSkipped, bool SourceFound)
{
/// <summary>
/// Source key ids that were NOT imported because SQL Server already holds a key whose id differs
/// only in case (since 0.4.4, Auth-008). SQLite compares key ids exactly, so <c>Line1</c> and
/// <c>line1</c> can both exist there; the SQL Server <c>key_id</c> primary key uses the database's
/// collation (case-insensitive by default) and cannot hold both. Such a key's token will not
/// verify against the shared store — re-mint it under a distinct id. Not counted in
/// <see cref="KeysSkipped"/>, which counts only exact duplicates.
/// </summary>
public IReadOnlyList<string> KeyIdCollisions { get; init; } = [];
/// <summary>
/// Source key ids that were NOT imported because a value exceeds its SQL Server column
/// (<c>key_id</c> 64, <c>key_prefix</c> 16, <c>display_name</c> 256 characters) (since 0.4.4,
/// Auth-008). Up to 0.4.3 such a row was imported silently truncated. Not counted in
/// <see cref="KeysSkipped"/>.
/// </summary>
public IReadOnlyList<string> KeysRejected { get; init; } = [];
}
/// <summary>
/// Copies every key and audit row from a per-node SQLite store into the shared SQL Server store,
/// insert-where-not-exists (keys by key_id; audit rows by key_id + event_type + created_utc), so it is
/// idempotent and every node of a pair may run it: the result is the UNION of the nodes' files. A row
/// that already exists in SQL Server is never modified — a revoke recorded on one node but not the
/// other therefore survives only if the revoked copy is imported first; operators reconcile by listing.
/// </summary>
/// <param name="sql">Factory for connections to the shared SQL Server API-key database.</param>
public sealed class SqliteApiKeyStoreImporter(AuthSqlServerConnectionFactory sql)
{
/// <summary>
/// Imports the keys and audit rows held in the SQLite store at <paramref name="sqlitePath"/>.
/// </summary>
/// <param name="sqlitePath">Path of the per-node SQLite API-key file.</param>
/// <param name="ct">A token to cancel the import.</param>
/// <returns>
/// The per-category insert/skip counts. When the file does not exist the result is all zeroes
/// with <see cref="ApiKeyImportResult.SourceFound"/> <see langword="false"/> and nothing is
/// opened — a host that has already imported (and renamed the file) pays nothing.
/// </returns>
/// <remarks>
/// <para>
/// The SQLite file is opened READ-ONLY and the schema migrator is deliberately NOT run against
/// it: the source is evidence, not something to upgrade. A file with no <c>api_keys</c> table is
/// treated as an empty source rather than an error, and a pre-v3 file (no <c>expires_utc</c>
/// column) reads its expiry as NULL = never expires, which is exactly what those keys meant.
/// </para>
/// <para>
/// Every row is read and the SQLite connection closed BEFORE any SQL Server write, and all the
/// writes then run inside ONE transaction. So the import is all-or-nothing: a failure part way
/// through rolls the transaction back and the exception propagates to the caller, leaving the
/// shared store exactly as it was. The host decides what that means — for a boot-time import,
/// logging and carrying on is usually right, because keys already in SQL Server keep working.
/// </para>
/// </remarks>
/// <exception cref="SqlException">A SQL Server write failed; nothing was committed.</exception>
/// <exception cref="SqliteException">The source file could not be read.</exception>
public async Task<ApiKeyImportResult> ImportAsync(string sqlitePath, CancellationToken ct)
{
ArgumentException.ThrowIfNullOrWhiteSpace(sqlitePath);
if (!File.Exists(sqlitePath))
{
return new ApiKeyImportResult(0, 0, 0, 0, SourceFound: false);
}
(IReadOnlyList<ApiKeyRecord> keys, IReadOnlyList<ApiKeyAuditEntry> auditEntries) =
await ReadSourceAsync(sqlitePath, ct).ConfigureAwait(false);
return await WriteAsync(keys, auditEntries, ct).ConfigureAwait(false);
}
// --- read side (SQLite) ---
private static async Task<(IReadOnlyList<ApiKeyRecord> Keys, IReadOnlyList<ApiKeyAuditEntry> Audit)>
ReadSourceAsync(string sqlitePath, CancellationToken ct)
{
SqliteConnectionStringBuilder builder = new()
{
DataSource = sqlitePath,
Mode = SqliteOpenMode.ReadOnly,
};
await using var connection = new SqliteConnection(builder.ToString());
await connection.OpenAsync(ct).ConfigureAwait(false);
IReadOnlyList<ApiKeyRecord> keys =
await TableExistsAsync(connection, SqliteAuthSchema.ApiKeysTable, ct).ConfigureAwait(false)
? await ReadKeysAsync(connection, ct).ConfigureAwait(false)
: [];
IReadOnlyList<ApiKeyAuditEntry> audit =
await TableExistsAsync(connection, SqliteAuthSchema.ApiKeyAuditTable, ct).ConfigureAwait(false)
? await ReadAuditAsync(connection, ct).ConfigureAwait(false)
: [];
return (keys, audit);
}
private static async Task<bool> TableExistsAsync(
SqliteConnection connection, string tableName, CancellationToken ct)
{
await using SqliteCommand command = connection.CreateCommand();
command.CommandText = """
SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = $table_name;
""";
command.Parameters.AddWithValue("$table_name", tableName);
return (long)(await command.ExecuteScalarAsync(ct).ConfigureAwait(false) ?? 0L) > 0;
}
private static async Task<IReadOnlyList<ApiKeyRecord>> ReadKeysAsync(
SqliteConnection connection, CancellationToken ct)
{
// A pre-v3 file has no expires_utc column, so select a literal NULL in its place rather than
// failing the import: NULL is precisely what those keys mean (never expires).
bool hasExpires = await ColumnExistsAsync(
connection, SqliteAuthSchema.ApiKeysTable, SqliteAuthSchema.ExpiresUtcColumn, ct).ConfigureAwait(false);
string expiresColumn = hasExpires ? SqliteAuthSchema.ExpiresUtcColumn : "NULL";
await using SqliteCommand command = connection.CreateCommand();
command.CommandText =
"SELECT key_id, key_prefix, secret_hash, display_name, scopes, constraints, " +
$"created_utc, last_used_utc, revoked_utc, {expiresColumn} FROM api_keys;";
List<ApiKeyRecord> keys = [];
await using SqliteDataReader reader = await command.ExecuteReaderAsync(ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
keys.Add(new ApiKeyRecord(
KeyId: reader.GetString(0),
KeyPrefix: reader.GetString(1),
SecretHash: reader.GetFieldValue<byte[]>(2),
DisplayName: reader.GetString(3),
Scopes: ScopeSerializer.Deserialize(reader.GetString(4)),
ConstraintsJson: reader.IsDBNull(5) ? null : reader.GetString(5),
CreatedUtc: SqliteValueParsing.ParseUtc(reader.GetString(6)),
LastUsedUtc: SqliteValueParsing.ReadNullableUtc(reader, 7),
RevokedUtc: SqliteValueParsing.ReadNullableUtc(reader, 8),
ExpiresUtc: SqliteValueParsing.ReadNullableUtc(reader, 9)));
}
return keys;
}
// SQLite has no information_schema; PRAGMA table_info is the column probe (the same one
// SqliteAuthStoreMigrator uses to decide whether its v3 ALTER TABLE is needed).
private static async Task<bool> ColumnExistsAsync(
SqliteConnection connection, string tableName, string columnName, CancellationToken ct)
{
await using SqliteCommand command = connection.CreateCommand();
// table_info takes an identifier, not a bindable parameter; the name is an internal constant.
command.CommandText = $"PRAGMA table_info({tableName});";
await using SqliteDataReader reader = await command.ExecuteReaderAsync(ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
// PRAGMA table_info columns: cid(0), name(1), type(2), ...
if (string.Equals(reader.GetString(1), columnName, StringComparison.OrdinalIgnoreCase))
{
return true;
}
}
return false;
}
private static async Task<IReadOnlyList<ApiKeyAuditEntry>> ReadAuditAsync(
SqliteConnection connection, CancellationToken ct)
{
await using SqliteCommand command = connection.CreateCommand();
// Insertion order, so the shared table's IDENTITY re-creates the source's ordering.
command.CommandText = """
SELECT key_id, event_type, remote_address, created_utc, details
FROM api_key_audit
ORDER BY audit_id;
""";
List<ApiKeyAuditEntry> entries = [];
await using SqliteDataReader reader = await command.ExecuteReaderAsync(ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
entries.Add(new ApiKeyAuditEntry(
KeyId: reader.IsDBNull(0) ? null : reader.GetString(0),
EventType: reader.GetString(1),
RemoteAddress: reader.IsDBNull(2) ? null : reader.GetString(2),
CreatedUtc: SqliteValueParsing.ParseUtc(reader.GetString(3)),
Details: reader.IsDBNull(4) ? null : reader.GetString(4)));
}
return entries;
}
// --- write side (SQL Server) ---
private async Task<ApiKeyImportResult> WriteAsync(
IReadOnlyList<ApiKeyRecord> keys,
IReadOnlyList<ApiKeyAuditEntry> auditEntries,
CancellationToken ct)
{
string schema = sql.Schema;
await using SqlConnection connection = await sql.OpenConnectionAsync(ct).ConfigureAwait(false);
await using SqlTransaction transaction =
(SqlTransaction)await connection.BeginTransactionAsync(ct).ConfigureAwait(false);
int keysInserted = 0;
int keysSkipped = 0;
int auditInserted = 0;
List<string> collisions = [];
List<string> rejected = [];
foreach (ApiKeyRecord key in keys)
{
// Refused rather than written truncated: a truncated key_id would verify only through an
// equally truncated lookup and authenticate as an id nobody assigned (Auth-008).
if (SqlServerColumnLimits.OverLengthField(key) is not null)
{
rejected.Add(key.KeyId);
continue;
}
switch (await InsertKeyIfAbsentAsync(connection, transaction, schema, key, ct).ConfigureAwait(false))
{
case KeyInsertOutcome.Inserted:
keysInserted++;
break;
case KeyInsertOutcome.AlreadyPresent:
keysSkipped++;
break;
default:
collisions.Add(key.KeyId);
break;
}
}
foreach (ApiKeyAuditEntry entry in auditEntries)
{
if (await InsertAuditIfAbsentAsync(connection, transaction, schema, entry, ct).ConfigureAwait(false))
{
auditInserted++;
}
}
await transaction.CommitAsync(ct).ConfigureAwait(false);
return new ApiKeyImportResult(
KeysInserted: keysInserted,
KeysSkipped: keysSkipped,
AuditInserted: auditInserted,
AuditSkipped: auditEntries.Count - auditInserted,
SourceFound: true)
{
KeyIdCollisions = collisions,
KeysRejected = rejected,
};
}
private enum KeyInsertOutcome
{
Inserted = 1,
AlreadyPresent = 0,
CaseVariantPresent = 2,
}
// The guard is inside the statement rather than a separate SELECT so the check and the insert
// cannot straddle a concurrent writer. The collation-aware `key_id = @key_id` finds a row whose
// id differs only in case — the primary key would refuse to hold both — and the exact match tells
// that collision apart from a genuine duplicate.
private async Task<KeyInsertOutcome> InsertKeyIfAbsentAsync(
SqlConnection connection,
SqlTransaction transaction,
string schema,
ApiKeyRecord key,
CancellationToken ct)
{
await using SqlCommand command = sql.CreateCommand(connection, $"""
IF EXISTS (
SELECT 1 FROM [{schema}].[{SqlServerAuthSchema.ApiKeysTable}]
WHERE key_id = @key_id AND {SqlServerColumnLimits.ExactKeyIdMatch})
SELECT 0;
ELSE IF EXISTS (
SELECT 1 FROM [{schema}].[{SqlServerAuthSchema.ApiKeysTable}] WHERE key_id = @key_id)
SELECT 2;
ELSE
BEGIN
INSERT INTO [{schema}].[{SqlServerAuthSchema.ApiKeysTable}] (
key_id, key_prefix, secret_hash, display_name, scopes,
constraints, created_utc, last_used_utc, revoked_utc, expires_utc)
VALUES (
@key_id, @key_prefix, @secret_hash, @display_name, @scopes,
@constraints, @created_utc, @last_used_utc, @revoked_utc, @expires_utc);
SELECT 1;
END
""", transaction);
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = key.KeyId;
command.Parameters.Add("@key_prefix", SqlDbType.NVarChar, 16).Value = key.KeyPrefix;
command.Parameters.Add("@secret_hash", SqlDbType.VarBinary, 64).Value = key.SecretHash;
command.Parameters.Add("@display_name", SqlDbType.NVarChar, 256).Value = key.DisplayName;
command.Parameters.Add("@scopes", SqlDbType.NVarChar, -1).Value = ScopeSerializer.Serialize(key.Scopes);
command.Parameters.Add("@constraints", SqlDbType.NVarChar, -1).Value = (object?)key.ConstraintsJson ?? DBNull.Value;
command.Parameters.Add("@created_utc", SqlDbType.DateTimeOffset).Value = key.CreatedUtc;
command.Parameters.Add("@last_used_utc", SqlDbType.DateTimeOffset).Value = (object?)key.LastUsedUtc ?? DBNull.Value;
command.Parameters.Add("@revoked_utc", SqlDbType.DateTimeOffset).Value = (object?)key.RevokedUtc ?? DBNull.Value;
command.Parameters.Add("@expires_utc", SqlDbType.DateTimeOffset).Value = (object?)key.ExpiresUtc ?? DBNull.Value;
object? outcome = await command.ExecuteScalarAsync(ct).ConfigureAwait(false);
return (KeyInsertOutcome)Convert.ToInt32(outcome, System.Globalization.CultureInfo.InvariantCulture);
}
// Audit rows carry no natural key (audit_id is per-file IDENTITY), so identity is the triple
// key_id + event_type + created_utc. key_id is nullable, hence the explicit NULL-safe arm: a
// plain `key_id = @key_id` is UNKNOWN, never true, when both sides are NULL.
private async Task<bool> InsertAuditIfAbsentAsync(
SqlConnection connection,
SqlTransaction transaction,
string schema,
ApiKeyAuditEntry entry,
CancellationToken ct)
{
await using SqlCommand command = sql.CreateCommand(connection, $"""
IF NOT EXISTS (
SELECT 1 FROM [{schema}].[{SqlServerAuthSchema.ApiKeyAuditTable}]
WHERE ((key_id = @key_id) OR (key_id IS NULL AND @key_id IS NULL))
AND event_type = @event_type
AND created_utc = @created_utc)
INSERT INTO [{schema}].[{SqlServerAuthSchema.ApiKeyAuditTable}] (
key_id, event_type, remote_address, created_utc, details)
VALUES (@key_id, @event_type, @remote_address, @created_utc, @details);
""", transaction);
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = (object?)entry.KeyId ?? DBNull.Value;
command.Parameters.Add("@event_type", SqlDbType.NVarChar, 64).Value = entry.EventType;
command.Parameters.Add("@remote_address", SqlDbType.NVarChar, 64).Value = (object?)entry.RemoteAddress ?? DBNull.Value;
command.Parameters.Add("@created_utc", SqlDbType.DateTimeOffset).Value = entry.CreatedUtc;
command.Parameters.Add("@details", SqlDbType.NVarChar, -1).Value = (object?)entry.Details ?? DBNull.Value;
return await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false) > 0;
}
}
@@ -0,0 +1,42 @@
<Project Sdk="Microsoft.NET.Sdk">
<ItemGroup>
<ProjectReference Include="..\ZB.MOM.WW.Auth.ApiKeys\ZB.MOM.WW.Auth.ApiKeys.csproj" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Data.SqlClient" />
<!--
Lightweight Microsoft.Extensions.* abstractions back the DI extension
(AddZbApiKeyAuthSqlServer, shipped by Task 6): IServiceCollection / TryAdd* / Configure
(DependencyInjection.Abstractions), IOptions (Options), IConfiguration
(Configuration.Abstractions), and IHostedService / AddHostedService (Hosting.Abstractions).
-->
<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
<PackageReference Include="Microsoft.Extensions.Options" />
<!-- Supplies the Configure<TOptions>(IConfiguration) binding overload used by the DI extension. -->
<PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" />
<PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" />
<PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" />
</ItemGroup>
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<PropertyGroup>
<IsPackable>true</IsPackable>
<PackageId>ZB.MOM.WW.Auth.ApiKeys.SqlServer</PackageId>
<Authors>ZB.MOM.WW</Authors>
<Description>SQL Server API-key store for the ZB.MOM.WW SCADA family — one shared row set for clustered hosts (central pairs).</Description>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/scadaproj/src/branch/main/ZB.MOM.WW.Auth</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/scadaproj</RepositoryUrl>
</PropertyGroup>
<ItemGroup>
<InternalsVisibleTo Include="ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests" />
</ItemGroup>
</Project>
@@ -33,10 +33,15 @@ public sealed class ApiKeyAdminCommands
private readonly IApiKeyAdminStore _adminStore;
private readonly IApiKeyAuditStore _auditStore;
private readonly IApiKeyPepperProvider _pepperProvider;
private readonly SqliteAuthStoreMigrator _migrator;
private readonly IApiKeyStoreMigrator _migrator;
private readonly TimeProvider _clock;
/// <summary>Creates the command set over the supplied stores and options.</summary>
/// <summary>
/// Creates the command set over the supplied stores and options.
/// Retained for existing consumers (MxAccessGateway, HistorianGateway, ScadaBridge) that
/// construct this type against the concrete SQLite migrator; forwards to the
/// <see cref="IApiKeyStoreMigrator"/> overload.
/// </summary>
/// <param name="options">API-key options (token prefix, store path, ...).</param>
/// <param name="adminStore">Mutating store (create / revoke / rotate / delete / list).</param>
/// <param name="auditStore">Append-only audit store wired into every mutating verb.</param>
@@ -50,6 +55,25 @@ public sealed class ApiKeyAdminCommands
IApiKeyPepperProvider pepperProvider,
SqliteAuthStoreMigrator migrator,
TimeProvider? clock = null)
: this(options, adminStore, auditStore, pepperProvider, (IApiKeyStoreMigrator)migrator, clock)
{
}
/// <summary>Creates the command set over the supplied stores and options.</summary>
/// <param name="options">API-key options (token prefix, store path, ...).</param>
/// <param name="adminStore">Mutating store (create / revoke / rotate / delete / list).</param>
/// <param name="auditStore">Append-only audit store wired into every mutating verb.</param>
/// <param name="pepperProvider">Resolves the pepper used to hash secrets.</param>
/// <param name="migrator">Schema migrator used by <see cref="InitDbAsync"/> — whichever store
/// provider's implementation (SQLite, SQL Server, ...) DI has registered.</param>
/// <param name="clock">Optional clock; defaults to <see cref="TimeProvider.System"/>.</param>
public ApiKeyAdminCommands(
ApiKeyOptions options,
IApiKeyAdminStore adminStore,
IApiKeyAuditStore auditStore,
IApiKeyPepperProvider pepperProvider,
IApiKeyStoreMigrator migrator,
TimeProvider? clock = null)
{
ArgumentNullException.ThrowIfNull(options);
ArgumentNullException.ThrowIfNull(adminStore);
@@ -261,7 +285,7 @@ public sealed class ApiKeyAdminCommands
string? pepper = _pepperProvider.GetPepper();
if (string.IsNullOrWhiteSpace(pepper))
{
throw new InvalidOperationException("pepper unavailable");
throw new ApiKeyPepperUnavailableException();
}
return pepper;
@@ -0,0 +1,34 @@
namespace ZB.MOM.WW.Auth.ApiKeys;
/// <summary>
/// Thrown when an API-key operation needs the secret pepper but
/// <see cref="IApiKeyPepperProvider.GetPepper"/> returned <c>null</c>, empty or whitespace
/// (create and rotate in <c>ApiKeyAdminCommands</c>).
/// </summary>
/// <remarks>
/// Derives from <see cref="InvalidOperationException"/>, which is what these paths threw before
/// this type existed, so existing <c>catch (InvalidOperationException)</c> blocks keep working.
/// The message stays <c>"pepper unavailable"</c>. Consumers can catch this type instead of
/// pre-checking <see cref="IApiKeyPepperProvider"/> themselves or matching the message. The verifier
/// does not throw it: a missing pepper surfaces there as <c>ApiKeyFailure.PepperUnavailable</c>.
/// </remarks>
public sealed class ApiKeyPepperUnavailableException : InvalidOperationException
{
/// <summary>Creates the exception with the default <c>"pepper unavailable"</c> message.</summary>
public ApiKeyPepperUnavailableException()
: base("pepper unavailable")
{
}
/// <summary>Creates the exception with a custom message.</summary>
public ApiKeyPepperUnavailableException(string message)
: base(message)
{
}
/// <summary>Creates the exception with a custom message and inner exception.</summary>
public ApiKeyPepperUnavailableException(string message, Exception innerException)
: base(message, innerException)
{
}
}
@@ -10,7 +10,8 @@ namespace ZB.MOM.WW.Auth.ApiKeys;
/// <remarks>
/// The failure reason is discriminated for the caller/audit pipeline, but the verifier returns a
/// structured result rather than throwing (the caller decides the opaque client-facing message).
/// The only exception path is cancellation. A successful identity carries the key's scopes and the
/// The only exception path is cancellation: a key-store lookup that faults is reported as
/// <see cref="ApiKeyFailure.StoreUnavailable"/> (since 0.4.4), and a failed last-used write is ignored. A successful identity carries the key's scopes and the
/// opaque <c>ConstraintsJson</c> blob (which the verifier does not interpret); it never carries the
/// presented secret, the pepper, or the stored secret hash.
/// </remarks>
@@ -44,7 +45,24 @@ public sealed class ApiKeyVerifier(
}
// 3. Look up the record (including revoked ones) so we can discriminate not-found vs revoked.
ApiKeyRecord? record = await store.FindByKeyIdAsync(parsed.KeyId, ct).ConfigureAwait(false);
// A store fault is a structured StoreUnavailable failure, not an exception (Auth-010): the
// store may be a shared network database, so "unreachable" is an operating condition, and
// consumers map Succeeded == false to their auth-failure path (and audit it) — an escaping
// SqlException became an unaudited 500 / gRPC Unknown instead. Cancellation still throws.
ApiKeyRecord? record;
try
{
record = await store.FindByKeyIdAsync(parsed.KeyId, ct).ConfigureAwait(false);
}
catch (OperationCanceledException)
{
throw;
}
catch (Exception)
{
return Fail(ApiKeyFailure.StoreUnavailable);
}
if (record is null)
{
return Fail(ApiKeyFailure.KeyNotFound);
@@ -1,17 +1,18 @@
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
namespace ZB.MOM.WW.Auth.ApiKeys.DependencyInjection;
/// <summary>
/// Runs the API-key SQLite schema migration at application startup when
/// <see cref="ApiKeyOptions.RunMigrationsOnStartup"/> is <see langword="true"/>.
/// The migration is idempotent, so repeated restarts are safe.
/// Runs the registered <see cref="IApiKeyStoreMigrator"/> at application startup when
/// <see cref="ApiKeyOptions.RunMigrationsOnStartup"/> is <see langword="true"/>. The migrator
/// registered in DI is whichever store provider's implementation won the <c>TryAdd</c> race —
/// SQLite by default, or a provider package (e.g. SQL Server) registered before
/// <c>AddZbApiKeyAuth</c>. The migration is idempotent, so repeated restarts are safe.
/// </summary>
internal sealed class ApiKeyMigrationHostedService(
SqliteAuthStoreMigrator migrator,
IApiKeyStoreMigrator migrator,
IOptions<ApiKeyOptions> options) : IHostedService
{
/// <inheritdoc />
@@ -61,10 +61,12 @@ public static class ApiKeyServiceCollectionExtensions
sp.GetRequiredService<IApiKeyStore>(),
sp.GetRequiredService<IApiKeyPepperProvider>()));
// Migrator: singleton, constructed from the already-registered connection factory.
// Needed before any store operations so the schema exists.
// Migrator: the SQLite implementation is the default; a provider package that registers
// IApiKeyStoreMigrator (and the three stores) BEFORE this call displaces it — that is the
// whole mechanism by which AddZbApiKeyAuthSqlServer swaps the backend.
services.TryAddSingleton(sp =>
new SqliteAuthStoreMigrator(sp.GetRequiredService<AuthSqliteConnectionFactory>()));
services.TryAddSingleton<IApiKeyStoreMigrator>(sp => sp.GetRequiredService<SqliteAuthStoreMigrator>());
// Hosted service that runs migrations on startup when ApiKeyOptions.RunMigrationsOnStartup.
services.AddHostedService<ApiKeyMigrationHostedService>();
@@ -1,5 +1,6 @@
using System.Globalization;
using Microsoft.Data.Sqlite;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;
@@ -11,7 +12,7 @@ public sealed class AuthStoreMigrationException(string message) : InvalidOperati
/// is safe to run repeatedly. Refuses to run against a database whose on-disk version
/// is newer than this build supports.
/// </summary>
public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connectionFactory)
public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connectionFactory) : IApiKeyStoreMigrator
{
/// <summary>Applies the schema migration to the auth store.</summary>
/// <param name="cancellationToken">Cancellation token.</param>
@@ -32,12 +32,15 @@
<PackageId>ZB.MOM.WW.Auth.ApiKeys</PackageId>
<Authors>ZB.MOM.WW</Authors>
<Description>SQLite-backed API-key store with pepper-based hashing for the ZB.MOM.WW SCADA family.</Description>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-auth</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-auth</RepositoryUrl>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/scadaproj/src/branch/main/ZB.MOM.WW.Auth</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/scadaproj</RepositoryUrl>
</PropertyGroup>
<ItemGroup>
<InternalsVisibleTo Include="ZB.MOM.WW.Auth.ApiKeys.Tests" />
<!-- Task 5's SqliteApiKeyStoreImporter parses SQLite values with SqliteValueParsing (internal)
rather than duplicating the parser. -->
<InternalsVisibleTo Include="ZB.MOM.WW.Auth.ApiKeys.SqlServer" />
</ItemGroup>
</Project>
@@ -22,7 +22,8 @@ public static class ServiceCollectionExtensions
/// <summary>
/// Registers LDAP authentication: binds and validates <see cref="LdapOptions"/> from the
/// configuration section at <paramref name="sectionPath"/>, and registers
/// <see cref="ILdapAuthService"/>.
/// <see cref="ILdapAuthService"/> and (0.5.0) <see cref="ILdapGroupLookup"/> — both resolve to the
/// same <see cref="LdapAuthService"/> instance.
/// </summary>
/// <param name="services">The service collection to add to.</param>
/// <param name="config">The application configuration.</param>
@@ -49,12 +50,35 @@ public static class ServiceCollectionExtensions
// Fail fast at startup on a misconfigured directory rather than on first login.
services.AddSingleton<IValidateOptions<LdapOptions>, LdapOptionsValidator>();
// LdapAuthService is stateless: it holds only a snapshot of LdapOptions and a stateless
// connection factory, and opens/disposes a connection per call. It is not IDisposable.
// Singleton is correct; TryAdd mirrors the pattern in AddZbApiKeyAuth (idempotency).
// LdapAuthService opens/disposes a connection per call and is not IDisposable. Its only
// mutable state is the sticky endpoint preference used by FallbackServers failover —
// which is precisely why the instance must be shared, so a primary-DC outage is paid
// for once rather than on every login. Singleton is correct; TryAdd mirrors the pattern
// in AddZbApiKeyAuth (idempotency). The logger is resolved with GetService, not
// GetRequiredService, so a host without logging configured still resolves the service.
services.TryAddSingleton<ILdapAuthService>(sp =>
new LdapAuthService(sp.GetRequiredService<IOptions<LdapOptions>>().Value));
new LdapAuthService(
sp.GetRequiredService<IOptions<LdapOptions>>().Value,
sp.GetService<Microsoft.Extensions.Logging.ILogger<LdapAuthService>>()));
// 0.5.0: the passwordless group lookup is the SAME instance as the auth service, so both share
// one sticky endpoint preference. A host that registered its own ILdapAuthService (a dev stub,
// a decorator) gets a lookup that answers NotSupported rather than a second, divergent client.
services.TryAddSingleton<ILdapGroupLookup>(sp =>
sp.GetRequiredService<ILdapAuthService>() as ILdapGroupLookup ?? UnsupportedLdapGroupLookup.Instance);
return services;
}
/// <summary>Answers every lookup with <see cref="LdapGroupLookupStatus.NotSupported"/>.</summary>
private sealed class UnsupportedLdapGroupLookup : ILdapGroupLookup
{
public static readonly UnsupportedLdapGroupLookup Instance = new();
public Task<LdapGroupLookupResult> GetUserGroupsAsync(string username, CancellationToken ct)
{
ct.ThrowIfCancellationRequested();
return Task.FromResult(LdapGroupLookupResult.Of(LdapGroupLookupStatus.NotSupported));
}
}
}
@@ -11,8 +11,8 @@
<PackageId>ZB.MOM.WW.Auth.AspNetCore</PackageId>
<Authors>ZB.MOM.WW</Authors>
<Description>ASP.NET Core DI helpers, cookie defaults, and claim mappings for the ZB.MOM.WW SCADA family.</Description>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-auth</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-auth</RepositoryUrl>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/scadaproj/src/branch/main/ZB.MOM.WW.Auth</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/scadaproj</RepositoryUrl>
</PropertyGroup>
<ItemGroup>
@@ -45,6 +45,22 @@ internal interface ILdapConnection : IDisposable
/// <summary>Executes a subtree search and returns all matching entries.</summary>
IReadOnlyList<LdapSearchEntry> Search(string searchBase, string filter, IReadOnlyList<string> attributes);
/// <summary>
/// Reads one entry by DN (a base-scope search) and returns the requested attributes the server
/// sent, or <see langword="null"/> when the entry does not exist. Throws <c>LdapException</c> on
/// any other failure. Used for constructed attributes such as AD's <c>msDS-PrincipalName</c>,
/// which a server may compute for a base read but not for a subtree search.
/// </summary>
LdapSearchEntry? Read(string dn, IReadOnlyList<string> attributes);
/// <summary>
/// RFC 4532 "Who am I?": the authorization identity the directory associates with the current
/// bind, as the server sends it (<c>dn:&lt;dn&gt;</c>, <c>u:DOMAIN\name</c>, or empty for an
/// anonymous bind). Throws <c>LdapException</c> when the server does not support the operation
/// (GLAuth answers protocol error 2).
/// </summary>
string WhoAmI();
}
/// <summary>Factory that produces <see cref="ILdapConnection"/> instances.</summary>
@@ -0,0 +1,60 @@
namespace ZB.MOM.WW.Auth.Ldap.Internal;
/// <summary>A single LDAP server endpoint resolved from configuration.</summary>
internal sealed record LdapEndpoint(string Host, int Port)
{
/// <summary>Renders the endpoint as <c>host:port</c> — the form used in failover log messages.</summary>
public override string ToString() => $"{Host}:{Port}";
}
/// <summary>
/// Parses <c>FallbackServers</c> entries: <c>"host"</c> (adopts the caller's default port)
/// or <c>"host:port"</c>. IPv6 literals are not supported — use a DNS name.
/// </summary>
internal static class LdapEndpointParser
{
/// <summary>
/// Attempts to parse a single <c>FallbackServers</c> entry.
/// </summary>
/// <param name="entry">The configured entry, <c>"host"</c> or <c>"host:port"</c>. Surrounding whitespace is tolerated.</param>
/// <param name="defaultPort">Port adopted when the entry carries no explicit one.</param>
/// <param name="endpoint">The parsed endpoint on success; undefined otherwise.</param>
/// <param name="error">A human-readable reason on failure; empty on success.</param>
/// <returns><see langword="true"/> when the entry parsed.</returns>
public static bool TryParse(string entry, int defaultPort, out LdapEndpoint endpoint, out string error)
{
endpoint = null!;
error = "";
if (string.IsNullOrWhiteSpace(entry))
{
error = "entry is empty or whitespace";
return false;
}
var parts = entry.Trim().Split(':');
if (parts.Length > 2)
{
error = $"entry \"{entry.Trim()}\" contains more than one ':' " +
"(IPv6 literals are not supported — use a DNS name)";
return false;
}
var host = parts[0].Trim();
if (host.Length == 0)
{
error = $"entry \"{entry.Trim()}\" has an empty host";
return false;
}
var port = defaultPort;
if (parts.Length == 2 && (!int.TryParse(parts[1].Trim(), out port) || port is < 1 or > 65535))
{
error = $"entry \"{entry.Trim()}\" has an invalid port (must be 1–65535)";
return false;
}
endpoint = new LdapEndpoint(host, port);
return true;
}
}
@@ -0,0 +1,60 @@
namespace ZB.MOM.WW.Auth.Ldap.Internal;
/// <summary>
/// Reduces a typed login to the bare account name used by <see cref="Abstractions.Ldap.LdapBindMode.User"/>:
/// the qualifier is stripped before the name reaches the bind template and the search filter, so audit
/// rows never carry <c>DOMAIN\jdoe</c> for one sign-in and <c>jdoe</c> for the next. Case is NOT
/// normalised here: the returned username is canonicalised from the directory entry's
/// <c>UserNameAttribute</c> value, so <c>JDoe</c> and <c>jdoe</c> also yield one identity; this name is
/// only the fallback when the entry has no such value.
/// </summary>
internal static class LdapUserName
{
/// <summary>
/// Trims <paramref name="input"/> and, when <paramref name="acceptDomainQualified"/>, strips one
/// leading <c>DOMAIN\</c> or one trailing <c>@suffix</c>. Returns <see langword="false"/> (with
/// <paramref name="name"/> empty) for blank input, for both forms at once, for a repeated
/// separator, for an empty side, or for any qualified form when <paramref name="acceptDomainQualified"/>
/// is <see langword="false"/>.
/// </summary>
public static bool TryNormalize(string? input, bool acceptDomainQualified, out string name)
{
name = "";
if (string.IsNullOrWhiteSpace(input))
return false;
var s = input.Trim();
var slash = s.IndexOf('\\');
var at = s.IndexOf('@');
if (slash >= 0 || at >= 0)
{
if (!acceptDomainQualified || (slash >= 0 && at >= 0))
return false;
if (slash >= 0)
{
if (slash == 0 || s.IndexOf('\\', slash + 1) >= 0)
return false;
s = s[(slash + 1)..];
}
else
{
// Unlike the slash branch (whose extracted suffix is checked for emptiness by the
// final length check below), the extracted piece here is the *prefix* — so an empty
// domain part (a trailing "@", e.g. "jdoe@") must be rejected explicitly.
if (at == s.Length - 1 || s.IndexOf('@', at + 1) >= 0)
return false;
s = s[..at];
}
s = s.Trim();
}
if (s.Length == 0)
return false;
name = s;
return true;
}
}
@@ -99,23 +99,107 @@ internal sealed class NovellLdapConnection : ILdapConnection
attributes.ToArray(),
typesOnly: false);
var entries = new List<LdapSearchEntry>();
while (results.HasMore())
return ReadEntries(results);
}
/// <inheritdoc/>
public LdapSearchEntry? Read(string dn, IReadOnlyList<string> attributes)
{
var results = _conn.Search(
dn,
LdapConnection.ScopeBase,
"(objectClass=*)",
attributes.ToArray(),
typesOnly: false);
try
{
var entry = results.Next();
var attrs = new Dictionary<string, IReadOnlyList<string>>(StringComparer.OrdinalIgnoreCase);
var entries = ReadEntries(results);
return entries.Count == 0 ? null : entries[0];
}
catch (LdapException ex) when (ex.ResultCode == LdapException.NoSuchObject)
{
return null;
}
}
foreach (LdapAttribute attr in entry.GetAttributeSet())
/// <inheritdoc/>
public string WhoAmI()
{
// ExtendedOperation throws LdapException on a non-success result (e.g. protocol error 2
// from a server without RFC 4532 support), which the caller treats as "no answer".
var response = _conn.ExtendedOperation(new LdapWhoAmIOperation());
if (response is LdapWhoAmIResponse whoAmI)
return whoAmI.AuthzId ?? "";
var value = response.Value;
return value is null ? "" : System.Text.Encoding.UTF8.GetString(value);
}
/// <summary>
/// Drains a result set into entries, <b>skipping continuation referrals</b>.
/// </summary>
/// <remarks>
/// <para>
/// Active Directory answers any search based at a domain root with one or more
/// continuation references (to <c>CN=Configuration</c>, <c>DC=ForestDnsZones</c> and
/// friends). With referral following disabled — the default, and what we want, since
/// chasing a referral would re-bind somewhere we did not authenticate — Novell surfaces
/// each one by throwing <see cref="LdapReferralException"/> from <see cref="ILdapSearchResults.Next"/>.
/// </para>
/// <para>
/// A continuation reference is a <em>pointer to another naming context</em>, not an error:
/// it says "there may be more results over there", never that this search failed. Letting
/// it escape made the whole search stage fail, which <c>LdapAuthService</c> maps to
/// <see cref="Abstractions.Ldap.LdapAuthFailure.ServiceAccountBindFailed"/> — so against a
/// real AD domain root, every login failed with a system-side error while the directory,
/// the credentials and both DCs were perfectly healthy. Verified against
/// <c>DC=nam,DC=zimmer,DC=com</c> on 2026-08-12.
/// </para>
/// <para>
/// Skipping is the correct behaviour rather than a workaround: the entries we can see are
/// exactly the ones in the naming context we bound to, which is the set the caller asked
/// about. Internal so the referral handling can be unit-tested through the
/// <see cref="ILdapSearchResults"/> seam without a live directory.
/// </para>
/// </remarks>
internal static List<LdapSearchEntry> ReadEntries(ILdapSearchResults results)
{
var entries = new List<LdapSearchEntry>();
var referrals = 0;
while (true)
{
try
{
attrs[attr.Name] = attr.StringValueArray.ToList();
}
if (!results.HasMore()) break;
entries.Add(new LdapSearchEntry(entry.Dn, attrs));
var entry = results.Next();
var attrs = new Dictionary<string, IReadOnlyList<string>>(StringComparer.OrdinalIgnoreCase);
foreach (LdapAttribute attr in entry.GetAttributeSet())
{
attrs[attr.Name] = attr.StringValueArray.ToList();
}
entries.Add(new LdapSearchEntry(entry.Dn, attrs));
}
catch (LdapException ex) when (ex is LdapReferralException || ex.ResultCode == LdapException.Referral)
{
// Novell dequeues the reference before throwing, so the enumeration advances and
// this terminates. The cap is a belt-and-braces guard: a client that threw without
// advancing would otherwise spin forever inside a fail-closed auth path, which is a
// far worse failure than under-reporting an implausible number of referrals.
if (++referrals > MaxReferrals) break;
}
}
return entries;
}
/// <summary>Upper bound on continuation references tolerated in one search — see <see cref="ReadEntries"/>.</summary>
private const int MaxReferrals = 1_000;
/// <inheritdoc/>
public void Dispose()
{
@@ -1,3 +1,4 @@
using Microsoft.Extensions.Logging;
using Novell.Directory.Ldap;
using ZB.MOM.WW.Auth.Abstractions.Ldap;
using ZB.MOM.WW.Auth.Ldap.Internal;
@@ -11,6 +12,7 @@ namespace ZB.MOM.WW.Auth.Ldap;
/// <see cref="ILdapConnection"/> so the logic is unit-testable without a live server.
/// </summary>
/// <remarks>
/// <para>
/// Fully fail-closed: authentication never throws to the caller — every error, expected
/// or unexpected, is mapped to a structured <see cref="LdapAuthResult.Fail(LdapAuthFailure)"/>.
/// A success is only returned for a user that resolved to exactly one entry, whose password
@@ -18,11 +20,42 @@ namespace ZB.MOM.WW.Auth.Ldap;
/// Service-account bind failures (<see cref="LdapAuthFailure.ServiceAccountBindFailed"/>) are
/// kept distinct from end-user bind failures (<see cref="LdapAuthFailure.BadCredentials"/>) so
/// a system misconfiguration is not mistaken for bad user input.
/// </para>
/// <para>
/// When <see cref="LdapOptions.FallbackServers"/> is non-empty the flow above runs against
/// an ordered endpoint list (primary first, then fallbacks in declared order) and moves on
/// to the next endpoint ONLY on a system-side failure — connect/TLS, service-account bind,
/// or search — i.e. when the endpoint gave no authoritative answer. Any answer from a healthy
/// directory (success, or a user-side failure such as
/// <see cref="LdapAuthFailure.BadCredentials"/> / <see cref="LdapAuthFailure.UserNotFound"/>)
/// is final and is never retried elsewhere: retrying a rejected password against a second DC
/// would turn one bad-password event into several, tripping account lockouts. Endpoint
/// preference is sticky — the last endpoint that answered is tried first next time — so a
/// primary outage costs its connect timeout once, not once per login.
/// </para>
/// <para>
/// The service is safe to share (it is registered as a singleton). The sticky index is the
/// only mutable state; concurrent logins may race on it, which is benign — the worst outcome
/// is one login starting at a stale endpoint and walking on.
/// </para>
/// <para>
/// With <c>BindMode = User</c> the service-account bind and the user re-bind are replaced by a
/// single bind as the user (<see cref="LdapOptions.UserBindTemplate"/>); see <see cref="CompleteAsUser"/>.
/// </para>
/// </remarks>
public sealed class LdapAuthService : ILdapAuthService
public sealed class LdapAuthService : ILdapAuthService, ILdapGroupLookup
{
private readonly LdapOptions _options;
private readonly ILdapConnectionFactory _connectionFactory;
private readonly IReadOnlyList<LdapEndpoint> _endpoints;
private readonly ILogger<LdapAuthService>? _logger;
/// <summary>
/// Index into <see cref="_endpoints"/> of the endpoint tried first. Written on any
/// authoritative answer from a non-preferred endpoint. Accessed via
/// <see cref="Volatile"/> only; benign races are accepted (see the type remarks).
/// </summary>
private int _preferredIndex;
/// <summary>
/// Production constructor: binds against a live directory via the real
@@ -31,9 +64,15 @@ public sealed class LdapAuthService : ILdapAuthService
/// <see cref="LdapOptions.AllowInsecure"/> bypass) is carried into the factory so each
/// connection is built with it.
/// </summary>
public LdapAuthService(LdapOptions options)
/// <param name="options">The directory connection and search settings.</param>
/// <param name="logger">
/// Optional. When supplied, endpoint failover is made visible: a Warning per failed
/// endpoint hop and an Information line when the sticky preference moves. Omitting it
/// (the default) leaves the service silent — hosts without logging still work.
/// </param>
public LdapAuthService(LdapOptions options, ILogger<LdapAuthService>? logger = null)
: this(options, new NovellLdapConnectionFactory(
options.AllowInsecure, options.ServerCertificateValidationCallback))
options.AllowInsecure, options.ServerCertificateValidationCallback), logger)
{
}
@@ -42,10 +81,33 @@ public sealed class LdapAuthService : ILdapAuthService
/// so the bind/search logic can be exercised without a live directory. Internal
/// because the connection seam is an implementation detail.
/// </summary>
internal LdapAuthService(LdapOptions options, ILdapConnectionFactory connectionFactory)
internal LdapAuthService(
LdapOptions options,
ILdapConnectionFactory connectionFactory,
ILogger<LdapAuthService>? logger = null)
{
_options = options;
_connectionFactory = connectionFactory;
_logger = logger;
_endpoints = BuildEndpoints(options);
}
/// <summary>
/// Primary first, then fallbacks in declared order. The validator rejects malformed
/// entries at boot; unparseable entries are skipped defensively here so a service
/// constructed without options validation degrades to the parseable subset rather
/// than throwing from a constructor.
/// </summary>
private static IReadOnlyList<LdapEndpoint> BuildEndpoints(LdapOptions options)
{
var endpoints = new List<LdapEndpoint> { new(options.Server, options.Port) };
foreach (var entry in options.FallbackServers)
{
if (LdapEndpointParser.TryParse(entry, options.Port, out var endpoint, out _))
endpoints.Add(endpoint);
}
return endpoints;
}
/// <inheritdoc />
@@ -54,7 +116,10 @@ public sealed class LdapAuthService : ILdapAuthService
/// bind-then-search-then-bind flow is wrapped so that any error — expected or unexpected —
/// is mapped to a structured <see cref="LdapAuthResult.Fail(LdapAuthFailure)"/>. A
/// <c>Succeeded == true</c> result is only ever returned when the user resolved to exactly
/// one entry, their password verified, AND at least one group was extracted.
/// one entry, their password verified, AND at least one group was extracted. With
/// <see cref="LdapOptions.FallbackServers"/> configured the flow may run against more than
/// one endpoint before answering — see the type-level remarks for the walk and its
/// system-side-only failover rule.
/// </remarks>
public Task<LdapAuthResult> AuthenticateAsync(string username, string password, CancellationToken ct)
{
@@ -80,112 +145,583 @@ public sealed class LdapAuthService : ILdapAuthService
// filter and the returned result (avoids two identities for one person).
username = username.Trim();
// 3b. An empty password must never reach the directory, in EITHER bind mode: AD answers a
// simple bind with an empty password as an UNAUTHENTICATED bind and reports success —
// the user bind (or the ServiceAccount-mode re-bind as the user's DN) would admit anyone.
// Refused here, before any network call, so no consumer depends on its own edge check.
if (string.IsNullOrEmpty(password))
return LdapAuthResult.Fail(LdapAuthFailure.BadCredentials);
// 3c. User-bind mode: reduce the name to the bare account name the bind template and the
// search filter share. (The returned username is canonicalised from the entry later.)
if (_options.BindMode == LdapBindMode.User
&& !LdapUserName.TryNormalize(username, _options.AcceptDomainQualifiedNames, out username))
{
return LdapAuthResult.Fail(LdapAuthFailure.BadCredentials);
}
// 4. Walk the endpoint list, preferred one first. A single-endpoint configuration
// (no FallbackServers) collapses to exactly one attempt — unchanged behaviour.
// ServiceAccountBindFailed is the (sole) system-side bucket: that endpoint gave no
// authoritative answer, so try the next one. Every other outcome — success, or a
// user-side failure like UserNotFound/BadCredentials — came from a healthy directory
// and is FINAL: re-asking a second DC about a rejected password would multiply one
// bad-password event into several against the account lockout policy.
// Seeded so an exhausted walk still returns the conservative system-side bucket
// even in the impossible case of an empty endpoint list.
return WalkEndpoints(
endpoint => AuthenticateAgainst(endpoint, username, password),
result => result.Failure == LdapAuthFailure.ServiceAccountBindFailed,
LdapAuthResult.Fail(LdapAuthFailure.ServiceAccountBindFailed));
}
/// <summary>
/// Runs <paramref name="attempt"/> against the endpoints, preferred one first, moving on only
/// while <paramref name="isSystemSide"/> says the endpoint gave no authoritative answer. The
/// first authoritative answer is returned and, if it came from a non-preferred endpoint, makes
/// that endpoint the sticky preference. An exhausted walk returns the last system-side result
/// (or <paramref name="exhausted"/>) and leaves the preference untouched: a total outage says
/// nothing about which endpoint to prefer once one recovers.
/// </summary>
private T WalkEndpoints<T>(Func<LdapEndpoint, T> attempt, Func<T, bool> isSystemSide, T exhausted)
{
var preferred = Volatile.Read(ref _preferredIndex);
if ((uint)preferred >= (uint)_endpoints.Count)
preferred = 0; // defensive: the list is immutable, but never index out of it
var last = exhausted;
foreach (var index in WalkOrder(_endpoints.Count, preferred))
{
var result = attempt(_endpoints[index]);
if (isSystemSide(result))
{
last = result;
continue;
}
// Sticky preference: any authoritative answer proves this endpoint healthy.
// Updating only on success would re-pay the dead primary's connect timeout on
// every mistyped password (or every refresh of a deleted user) for the whole outage.
if (index != preferred)
{
Volatile.Write(ref _preferredIndex, index);
_logger?.LogInformation("LDAP sticky preference moved to {Endpoint}.", _endpoints[index]);
}
return result;
}
return last;
}
/// <summary>Preferred endpoint first, then every other endpoint in declared order.</summary>
private static IEnumerable<int> WalkOrder(int count, int preferred)
{
yield return preferred;
for (var i = 0; i < count; i++)
{
if (i != preferred)
yield return i;
}
}
/// <summary>
/// Runs one full bind-then-search-then-bind attempt against a single endpoint on a fresh
/// connection. The fail-closed contract holds per attempt: this never throws, and it
/// returns <see cref="LdapAuthFailure.ServiceAccountBindFailed"/> for — and only for —
/// system-side faults, which is what the caller reads as "no authoritative answer, try
/// the next endpoint".
/// </summary>
private LdapAuthResult AuthenticateAgainst(LdapEndpoint endpoint, string username, string password)
{
// The whole flow runs inside an outer fail-closed guard: a StageFailure carries an
// already-mapped failure out of a stage, and any OTHER unexpected exception defaults to
// the most conservative system-side bucket. Either way the caller gets a structured result.
try
{
// A fresh connection per attempt: a Novell connection that has failed to connect
// or bind is not safely reusable against another host.
using var conn = _connectionFactory.Create();
// 4. Open the connection (transport/TLS handling lives in the adapter). The
// 5. Open the connection (transport/TLS handling lives in the adapter). The
// per-operation timeout (ConnectionTimeoutMs) is applied by the adapter here.
// A failure to connect/upgrade means the directory is unreachable — a
// system-side fault, not the user's, so map it to ServiceAccountBindFailed.
// A failure to connect/upgrade means this endpoint is unreachable — a
// system-side fault, not the user's, so map it to ServiceAccountBindFailed
// and let the caller try the next endpoint.
// NOTE: the LdapAuthFailure enum has no dedicated DirectoryUnavailable value;
// ServiceAccountBindFailed is the closest system-side bucket. A future
// Abstractions change could add DirectoryUnavailable to disambiguate.
try
{
conn.Connect(
_options.Server,
_options.Port,
_options.Transport,
_options.AllowInsecure,
_options.ConnectionTimeoutMs,
_options.ServerCertificateValidationCallback);
}
catch (LdapException)
{
throw new StageFailure(LdapAuthFailure.ServiceAccountBindFailed);
}
ConnectTo(conn, endpoint);
return _options.BindMode == LdapBindMode.User
? CompleteAsUser(conn, username, password)
: CompleteWithServiceAccount(conn, username, password);
}
catch (StageFailure stage)
{
// A stage mapped its own failure; surface it as a structured result. Log at Warning
// so a silent failover — the failure mode this feature exists to survive — is
// visible in the host's log rather than only in a latency graph.
_logger?.LogWarning(
"LDAP endpoint {Endpoint} failed system-side at {Stage}; treating as no answer.",
endpoint, stage.Stage);
return LdapAuthResult.Fail(stage.Failure);
}
catch (Exception ex)
{
// Belt-and-braces: ANY unexpected exception fails closed to the most conservative
// system-side bucket rather than propagating to the caller.
_logger?.LogWarning(ex, "LDAP endpoint {Endpoint} failed system-side with an unexpected error.", endpoint);
return LdapAuthResult.Fail(LdapAuthFailure.ServiceAccountBindFailed);
}
}
/// <inheritdoc />
/// <remarks>
/// Fail-closed like <see cref="AuthenticateAsync"/>: never throws to the caller (cancellation is
/// observed at entry only). Uses the service account in every case, so it is
/// <see cref="LdapGroupLookupStatus.NotSupported"/> in <see cref="LdapBindMode.User"/> mode. The
/// name is normalised exactly as <see cref="AuthenticateAsync"/> normalises it in
/// <see cref="LdapBindMode.ServiceAccount"/> mode (trimmed, otherwise verbatim), so a name a session
/// was issued for resolves to the same entry. The endpoint walk, sticky preference, timeouts and
/// TLS policy are shared with authentication; only a system-side failure moves to the next
/// endpoint. Credentials are never logged.
/// </remarks>
public Task<LdapGroupLookupResult> GetUserGroupsAsync(string username, CancellationToken ct)
{
ct.ThrowIfCancellationRequested();
return Task.FromResult(LookupGroups(username));
}
private LdapGroupLookupResult LookupGroups(string username)
{
if (!_options.Enabled)
return LdapGroupLookupResult.Of(LdapGroupLookupStatus.ProviderDisabled);
// User mode has no service account to search with, and a blank service-account DN would bind
// anonymously — the validator refuses that at boot; refuse it here too for unvalidated hosts.
if (_options.BindMode == LdapBindMode.User || string.IsNullOrWhiteSpace(_options.ServiceAccountDn))
return LdapGroupLookupResult.Of(LdapGroupLookupStatus.NotSupported);
if (string.IsNullOrWhiteSpace(username))
return LdapGroupLookupResult.Of(LdapGroupLookupStatus.UserNotFound);
username = username.Trim();
return WalkEndpoints(
endpoint => LookupAgainst(endpoint, username),
result => result.Status == LdapGroupLookupStatus.DirectoryUnavailable,
LdapGroupLookupResult.Of(LdapGroupLookupStatus.DirectoryUnavailable));
}
/// <summary>
/// One lookup attempt against one endpoint on a fresh connection: connect, service-account bind,
/// search. A fault in any of those is <see cref="LdapGroupLookupStatus.DirectoryUnavailable"/> (try
/// the next endpoint); every other status is the directory's answer.
/// </summary>
private LdapGroupLookupResult LookupAgainst(LdapEndpoint endpoint, string username)
{
try
{
using var conn = _connectionFactory.Create();
ConnectTo(conn, endpoint);
// 5. Service-account bind so we can search for the user's DN. A bind failure
// here is a service-account misconfiguration — DISTINCT from a user-credential
// failure — so it maps to ServiceAccountBindFailed.
try
{
conn.Bind(_options.ServiceAccountDn, _options.ServiceAccountPassword);
}
catch (LdapException)
{
throw new StageFailure(LdapAuthFailure.ServiceAccountBindFailed);
throw new StageFailure(LdapAuthFailure.ServiceAccountBindFailed, "service-bind");
}
// 6. Search for the user entry by the configured username attribute. A search
// failure is infrastructure (directory unreachable / unhealthy) — system-side.
// NOTE: same enum limitation as Connect above; ServiceAccountBindFailed is the
// closest system-side bucket until a DirectoryUnavailable value exists.
IReadOnlyList<LdapSearchEntry> entries;
try
{
var filter = $"({_options.UserNameAttribute}={LdapEscaping.Filter(username)})";
entries = conn.Search(_options.SearchBase, filter, BuildSearchAttributes());
}
catch (LdapException)
{
throw new StageFailure(LdapAuthFailure.ServiceAccountBindFailed);
}
// 7. Require exactly one match. Zero -> UserNotFound; two or more -> AmbiguousUser.
// We never attempt a user bind against an ambiguous DN.
var entries = SearchUser(conn, username, UserAccountControlAttribute);
if (entries.Count == 0)
return LdapAuthResult.Fail(LdapAuthFailure.UserNotFound);
return LdapGroupLookupResult.Of(LdapGroupLookupStatus.UserNotFound);
if (entries.Count >= 2)
return LdapAuthResult.Fail(LdapAuthFailure.AmbiguousUser);
return LdapGroupLookupResult.Of(LdapGroupLookupStatus.AmbiguousUser);
var entry = entries[0];
if (IsAccountDisabled(entry))
return LdapGroupLookupResult.Of(LdapGroupLookupStatus.UserDisabled);
// 8. User bind: re-bind as the resolved DN to verify the password. A bind failure
// here is the end user's bad credentials.
try
{
conn.Bind(entry.Dn, password);
}
catch (LdapException)
{
throw new StageFailure(LdapAuthFailure.BadCredentials);
}
// 9. Group extraction. Fail closed: an empty/missing group set, or any error while
// extracting groups, is a GroupLookupFailed — never a zero-group success.
IReadOnlyList<string> groups;
try
{
groups = ExtractGroups(entry);
}
catch
{
throw new StageFailure(LdapAuthFailure.GroupLookupFailed);
}
if (groups.Count == 0)
return LdapAuthResult.Fail(LdapAuthFailure.GroupLookupFailed);
// 10. Success — and only here, with a verified password and >= 1 group.
var displayName = ExtractDisplayName(entry, username);
return LdapAuthResult.Success(username, displayName, groups);
var canonical = ExtractUserName(entry, username);
return LdapGroupLookupResult.Found(canonical, ExtractDisplayName(entry, canonical), ExtractGroups(entry));
}
catch (StageFailure stage)
{
// A stage mapped its own failure; surface it as a structured result.
return LdapAuthResult.Fail(stage.Failure);
_logger?.LogWarning(
"LDAP endpoint {Endpoint} failed system-side at {Stage} during a group lookup; treating as no answer.",
endpoint, stage.Stage);
return LdapGroupLookupResult.Of(LdapGroupLookupStatus.DirectoryUnavailable);
}
catch (Exception ex)
{
_logger?.LogWarning(ex, "LDAP endpoint {Endpoint} failed system-side with an unexpected error during a group lookup.", endpoint);
return LdapGroupLookupResult.Of(LdapGroupLookupStatus.DirectoryUnavailable);
}
}
/// <summary>AD's account-flags attribute; absent on directories that do not model it (GLAuth, OpenLDAP).</summary>
private const string UserAccountControlAttribute = "userAccountControl";
/// <summary>AD <c>userAccountControl</c> ACCOUNTDISABLE flag.</summary>
private const int AccountDisableFlag = 0x2;
/// <summary>
/// <see langword="true"/> when the entry carries AD's <c>userAccountControl</c> with ACCOUNTDISABLE set.
/// An absent or unparseable value is "not disabled": directories without the attribute have no such
/// state, and a password bind is what refuses a disabled account at sign-in anyway.
/// </summary>
private static bool IsAccountDisabled(LdapSearchEntry entry)
=> entry.Attributes.TryGetValue(UserAccountControlAttribute, out var values)
&& values.Count > 0
&& int.TryParse(values[0], System.Globalization.NumberStyles.Integer,
System.Globalization.CultureInfo.InvariantCulture, out var flags)
&& (flags & AccountDisableFlag) != 0;
/// <summary>Opens the connection; a connect/TLS fault means this endpoint is unreachable (system-side).</summary>
private void ConnectTo(ZB.MOM.WW.Auth.Ldap.Internal.ILdapConnection conn, LdapEndpoint endpoint)
{
try
{
conn.Connect(
endpoint.Host,
endpoint.Port,
_options.Transport,
_options.AllowInsecure,
_options.ConnectionTimeoutMs,
_options.ServerCertificateValidationCallback);
}
catch (LdapException)
{
throw new StageFailure(LdapAuthFailure.ServiceAccountBindFailed, "connect");
}
}
/// <summary>Steps 6–11 of the 0.3.0 flow: service-account bind, search, user re-bind, groups.</summary>
private LdapAuthResult CompleteWithServiceAccount(ZB.MOM.WW.Auth.Ldap.Internal.ILdapConnection conn, string username, string password)
{
// 6. Service-account bind so we can search for the user's DN. A bind failure here is a
// service-account misconfiguration — DISTINCT from a user-credential failure — so it
// maps to ServiceAccountBindFailed.
try
{
conn.Bind(_options.ServiceAccountDn, _options.ServiceAccountPassword);
}
catch (LdapException)
{
throw new StageFailure(LdapAuthFailure.ServiceAccountBindFailed, "service-bind");
}
// 7–8. Require exactly one match. Zero -> UserNotFound; two or more -> AmbiguousUser.
// Both are authoritative answers from a healthy directory, so they end the walk.
// We never attempt a user bind against an ambiguous DN.
var entries = SearchUser(conn, username);
if (entries.Count == 0)
return LdapAuthResult.Fail(LdapAuthFailure.UserNotFound);
if (entries.Count >= 2)
return LdapAuthResult.Fail(LdapAuthFailure.AmbiguousUser);
var entry = entries[0];
// 9. User bind: re-bind as the resolved DN to verify the password. A bind failure here is
// the end user's bad credentials — the directory answered, so this is returned directly
// and never retried against another endpoint.
try
{
conn.Bind(entry.Dn, password);
}
catch (LdapException)
{
return LdapAuthResult.Fail(LdapAuthFailure.BadCredentials);
}
return SucceedFromEntry(entry, username);
}
/// <summary>
/// <see cref="LdapBindMode.User"/>: the user's own bind is the authentication; the same
/// connection then reads their entry. Only result 49 (invalid credentials — AD's answer for a
/// wrong password AND for unknown, locked, disabled or expired accounts) is the user's failure
/// and final; any other bind error means this endpoint gave no answer, so the walk moves on.
/// </summary>
/// <remarks>
/// The bind name (from <see cref="LdapOptions.UserBindTemplate"/>) and the search filter
/// (<see cref="LdapOptions.UserNameAttribute"/>) are resolved by two different directory
/// lookups, so they can name two different accounts — e.g. a UPN bind that AD resolves to the
/// account whose explicit <c>userPrincipalName</c> is <c>jsmith@corp</c> while the search finds
/// the account whose <c>sAMAccountName</c> is <c>jsmith</c> (Auth-007). The entry is therefore
/// only accepted when it is provably the account that bound: see <see cref="ResolveBoundIdentity"/>
/// and <see cref="IsBoundAccount"/>. Anything else is <see cref="LdapAuthFailure.GroupLookupFailed"/>.
/// </remarks>
private LdapAuthResult CompleteAsUser(ZB.MOM.WW.Auth.Ldap.Internal.ILdapConnection conn, string username, string password)
{
var dnTemplate = IsDnTemplate(_options.UserBindTemplate);
// A DN template splices the name into a DN, so the name is RFC 4514-escaped: unescaped, a
// name like "x,ou=other" would bind a DN of the caller's choosing.
var bindName = _options.UserBindTemplate.Replace(
"{0}", dnTemplate ? LdapEscaping.Dn(username) : username, StringComparison.Ordinal);
try
{
conn.Bind(bindName, password);
}
catch (LdapException ex) when (ex.ResultCode == LdapException.InvalidCredentials)
{
return LdapAuthResult.Fail(LdapAuthFailure.BadCredentials);
}
catch (LdapException)
{
throw new StageFailure(LdapAuthFailure.ServiceAccountBindFailed, "user-bind");
}
var bound = ResolveBoundIdentity(conn, bindName, dnTemplate);
if (bound is null)
{
_logger?.LogWarning(
"LDAP user bind succeeded but the bound identity could not be established (no RFC 4532 " +
"Who-am-I answer and UserBindTemplate is not a DN); refusing the sign-in.");
return LdapAuthResult.Fail(LdapAuthFailure.GroupLookupFailed);
}
// After a good bind, anything but exactly one readable entry is a failure to establish the
// user's groups — never a success, and never UserNotFound (the directory just accepted them).
var entries = SearchUser(conn, username, bound.AccountName is null ? null : SamAccountNameAttribute);
if (entries.Count != 1)
return LdapAuthResult.Fail(LdapAuthFailure.GroupLookupFailed);
if (!IsBoundAccount(conn, entries[0], bound, username))
{
_logger?.LogWarning(
"LDAP user bind authenticated {BoundIdentity} but the entry found for the typed name is " +
"{EntryDn}; refusing the sign-in rather than returning another account's groups.",
bound, entries[0].Dn);
return LdapAuthResult.Fail(LdapAuthFailure.GroupLookupFailed);
}
return SucceedFromEntry(entries[0], username);
}
/// <summary>The AD attribute that an RFC 4532 <c>u:DOMAIN\name</c> authorization identity names.</summary>
private const string SamAccountNameAttribute = "sAMAccountName";
/// <summary>AD's constructed attribute holding a principal's <c>DOMAIN\name</c>, derived from its <c>objectSid</c>.</summary>
private const string PrincipalNameAttribute = "msDS-PrincipalName";
/// <summary>
/// The account a user bind authenticated: either its DN, or (AD's Who-am-I form) its
/// <c>sAMAccountName</c> plus, when the answer carried one, its NetBIOS <see cref="Domain"/>.
/// Exactly one of <see cref="Dn"/> / <see cref="AccountName"/> is set.
/// </summary>
private sealed record BoundIdentity(string? Dn, string? AccountName, string? Domain = null)
{
public override string ToString() =>
Dn is not null ? $"dn:{Dn}" : Domain is null ? $"u:{AccountName}" : $@"u:{Domain}\{AccountName}";
}
/// <summary>A template is a DN template when it contains an attribute assertion (<c>=</c>); UPN and down-level forms never do.</summary>
private static bool IsDnTemplate(string template) => template.Contains('=', StringComparison.Ordinal);
/// <summary>
/// Establishes which account the bind authenticated. The directory's own answer wins: RFC 4532
/// Who-am-I (<c>dn:&lt;dn&gt;</c>, or AD's <c>u:DOMAIN\name</c>). Without one — the server does
/// not support the operation (GLAuth), or answers empty — a DN template is still provable,
/// because the directory accepted exactly that DN; a UPN or down-level template is not, so the
/// result is <see langword="null"/> and the sign-in fails closed.
/// </summary>
private static BoundIdentity? ResolveBoundIdentity(
ZB.MOM.WW.Auth.Ldap.Internal.ILdapConnection conn, string bindName, bool dnTemplate)
{
string authzId;
try
{
authzId = conn.WhoAmI()?.Trim() ?? "";
}
catch (LdapException)
{
// Unsupported (protocol error / unwilling) or a transport fault. Either way there is no
// answer; a dead connection will fail the following search, which is system-side.
authzId = "";
}
if (authzId.StartsWith("dn:", StringComparison.OrdinalIgnoreCase) && authzId.Length > 3)
return new BoundIdentity(authzId[3..].Trim(), null);
if (authzId.StartsWith("u:", StringComparison.OrdinalIgnoreCase) && authzId.Length > 2)
{
var account = authzId[2..].Trim();
string? domain = null;
var slash = account.LastIndexOf('\\');
if (slash >= 0)
{
domain = account[..slash].Trim();
account = account[(slash + 1)..];
}
if (account.Length > 0)
return new BoundIdentity(null, account, string.IsNullOrEmpty(domain) ? null : domain);
}
return dnTemplate ? new BoundIdentity(bindName, null) : null;
}
/// <summary>
/// <see langword="true"/> only when <paramref name="entry"/> is the account that bound: its DN
/// equals the bound DN (RFC 4514 <c>distinguishedNameMatch</c>, case- and space-insensitive), or
/// — for AD's <c>u:DOMAIN\name</c> answer — it is provably that domain's account of that name
/// (see <see cref="IsBoundAdAccount"/>).
/// </summary>
private bool IsBoundAccount(
ZB.MOM.WW.Auth.Ldap.Internal.ILdapConnection conn, LdapSearchEntry entry, BoundIdentity bound, string username)
{
if (bound.Dn is not null)
{
try
{
return LdapDn.Equals(entry.Dn, bound.Dn);
}
catch (Exception)
{
// An unparseable DN on either side cannot be proven equal.
return false;
}
}
return IsBoundAdAccount(conn, entry, bound, username);
}
/// <summary>
/// The <c>u:DOMAIN\name</c> case. A matching <c>sAMAccountName</c> is necessary but not enough:
/// <c>sAMAccountName</c> is unique per DOMAIN, so a search base that spans a forest (a Global
/// Catalog) can find another domain's account of the same name and hand back its groups
/// (scadaproj#50). In order of strength:
/// <list type="number">
/// <item>Where the directory offers AD's constructed <c>msDS-PrincipalName</c> for the entry —
/// its <c>DOMAIN\name</c>, computed from the entry's <c>objectSid</c> — it must equal the
/// Who-am-I answer, domain included. That is the decisive, SID-anchored check. (The bound
/// account's own <c>objectSid</c> cannot be compared directly: Who-am-I does not return it.)</item>
/// <item>Otherwise the name must have exactly ONE holder under <see cref="LdapOptions.SearchBase"/>,
/// and that holder's DN must be the entry's: two holders mean which one bound cannot be proven,
/// so the sign-in fails closed. The user search already proves this when it was itself
/// <c>(sAMAccountName=&lt;the bound name&gt;)</c> and found one entry, so no second search is
/// made then. Residual: a search base that covers another domain's holder but NOT the bound
/// account's own domain is not detectable without <c>msDS-PrincipalName</c>.</item>
/// </list>
/// </summary>
private bool IsBoundAdAccount(
ZB.MOM.WW.Auth.Ldap.Internal.ILdapConnection conn, LdapSearchEntry entry, BoundIdentity bound, string username)
{
if (!entry.Attributes.TryGetValue(SamAccountNameAttribute, out var values)
|| values.Count != 1
|| !string.Equals(values[0], bound.AccountName, StringComparison.OrdinalIgnoreCase))
{
return false;
}
if (bound.Domain is not null && ReadPrincipalName(conn, entry.Dn) is { } principal)
return string.Equals(principal, $@"{bound.Domain}\{bound.AccountName}", StringComparison.OrdinalIgnoreCase);
var searchedOnTheBoundName =
string.Equals(_options.UserNameAttribute, SamAccountNameAttribute, StringComparison.OrdinalIgnoreCase)
&& string.Equals(username, bound.AccountName, StringComparison.OrdinalIgnoreCase);
if (searchedOnTheBoundName)
return true;
IReadOnlyList<LdapSearchEntry> holders;
try
{
holders = conn.Search(
_options.SearchBase,
$"({SamAccountNameAttribute}={LdapEscaping.Filter(bound.AccountName!)})",
new[] { SamAccountNameAttribute });
}
catch (LdapException)
{
// Same bucket as the user search: the directory could not answer, which is system-side.
throw new StageFailure(LdapAuthFailure.ServiceAccountBindFailed, "search");
}
if (holders.Count != 1)
return false;
try
{
return LdapDn.Equals(holders[0].Dn, entry.Dn);
}
catch (Exception)
{
return false;
}
}
/// <summary>
/// The entry's <c>msDS-PrincipalName</c> when the directory computes one in <c>DOMAIN\name</c>
/// form; <see langword="null"/> when it is absent, unreadable, or a SID string (AD's form for a
/// principal it cannot name) — all of which mean "not available", never "mismatch".
/// </summary>
private static string? ReadPrincipalName(ZB.MOM.WW.Auth.Ldap.Internal.ILdapConnection conn, string dn)
{
try
{
var read = conn.Read(dn, new[] { PrincipalNameAttribute });
if (read is not null
&& read.Attributes.TryGetValue(PrincipalNameAttribute, out var values)
&& values.Count == 1
&& values[0].Contains('\\', StringComparison.Ordinal))
{
return values[0].Trim();
}
}
catch (LdapException)
{
// Not offered, or not readable by this account: fall back to the uniqueness check.
}
return null;
}
/// <summary>Step 7: search for the user entry; a search fault is system-side.</summary>
private IReadOnlyList<LdapSearchEntry> SearchUser(
ZB.MOM.WW.Auth.Ldap.Internal.ILdapConnection conn, string username, string? extraAttribute = null)
{
// A search failure is infrastructure (directory unreachable / unhealthy) — system-side.
// NOTE: the LdapAuthFailure enum has no DirectoryUnavailable value, so a failed search maps
// to ServiceAccountBindFailed, the closest system-side bucket (same limitation as
// Connect), until a DirectoryUnavailable value exists.
try
{
var filter = $"({_options.UserNameAttribute}={LdapEscaping.Filter(username)})";
return conn.Search(_options.SearchBase, filter, BuildSearchAttributes(extraAttribute));
}
catch (LdapException)
{
throw new StageFailure(LdapAuthFailure.ServiceAccountBindFailed, "search");
}
}
/// <summary>
/// Steps 10–11: fail-closed group extraction, then success. The returned username is the
/// entry's own <see cref="LdapOptions.UserNameAttribute"/> value (the directory's spelling), so
/// <c>JDoe</c> and <c>jdoe</c> sign in as one identity; the typed (normalised) name is the
/// fallback when the entry carries no such value.
/// </summary>
private LdapAuthResult SucceedFromEntry(LdapSearchEntry entry, string username)
{
IReadOnlyList<string> groups;
try
{
groups = ExtractGroups(entry);
}
catch
{
// Belt-and-braces: ANY unexpected exception fails closed to the most conservative
// system-side bucket rather than propagating to the caller.
return LdapAuthResult.Fail(LdapAuthFailure.ServiceAccountBindFailed);
return LdapAuthResult.Fail(LdapAuthFailure.GroupLookupFailed);
}
if (groups.Count == 0)
return LdapAuthResult.Fail(LdapAuthFailure.GroupLookupFailed);
var canonical = ExtractUserName(entry, username);
return LdapAuthResult.Success(canonical, ExtractDisplayName(entry, canonical), groups);
}
/// <summary>
@@ -194,22 +730,61 @@ public sealed class LdapAuthService : ILdapAuthService
/// </summary>
private sealed class StageFailure : Exception
{
public StageFailure(LdapAuthFailure failure) => Failure = failure;
public StageFailure(LdapAuthFailure failure, string stage)
{
Failure = failure;
Stage = stage;
}
public LdapAuthFailure Failure { get; }
/// <summary>Which stage faulted (<c>connect</c> / <c>service-bind</c> / <c>user-bind</c> / <c>search</c>), for diagnostics.</summary>
public string Stage { get; }
}
/// <summary>
/// Builds the distinct attribute list requested from the directory. The display-name
/// and group attributes are de-duplicated so we never request the same attribute twice
/// when an operator configures them to the same value.
/// Builds the distinct attribute list requested from the directory: display name, groups,
/// the username attribute (read back as the canonical username) and, when the user-bind
/// identity check needs it, <paramref name="extraAttribute"/>. They are de-duplicated,
/// case-insensitively, so we never request the same attribute twice when an operator
/// configures two of them to the same value.
/// </summary>
private IReadOnlyList<string> BuildSearchAttributes()
private IReadOnlyList<string> BuildSearchAttributes(string? extraAttribute = null)
{
if (string.Equals(_options.DisplayNameAttribute, _options.GroupAttribute, StringComparison.OrdinalIgnoreCase))
return new[] { _options.DisplayNameAttribute };
var attributes = new List<string>(4);
foreach (var name in new[] { _options.DisplayNameAttribute, _options.GroupAttribute, _options.UserNameAttribute, extraAttribute })
{
if (name is not null && !attributes.Contains(name, StringComparer.OrdinalIgnoreCase))
attributes.Add(name);
}
return new[] { _options.DisplayNameAttribute, _options.GroupAttribute };
return attributes;
}
/// <summary>
/// Returns the directory's spelling of the name the user matched on: the value of the configured
/// username attribute that equals the typed (already normalised) name ignoring case. Only when no
/// value does is the first non-blank value used, and only when there is none the typed name.
/// </summary>
/// <remarks>
/// The attribute can be multi-valued — the default <c>cn</c> is, and OpenLDAP / 389-DS entries
/// routinely carry both <c>cn: John Smith</c> and <c>cn: jsmith</c>. 0.4.1 returned whichever
/// value the server listed first, so <c>jsmith</c> could sign in as <c>John Smith</c> depending on
/// attribute ordering (Auth-009). Matching ordinal-ignore-case still canonicalises case
/// (<c>JSMITH</c> → <c>jsmith</c>), which is what 0.4.1 set out to do.
/// </remarks>
private string ExtractUserName(LdapSearchEntry entry, string username)
{
if (!entry.Attributes.TryGetValue(_options.UserNameAttribute, out var values) || values.Count == 0)
return username;
foreach (var value in values)
{
if (string.Equals(value, username, StringComparison.OrdinalIgnoreCase))
return value;
}
return string.IsNullOrWhiteSpace(values[0]) ? username : values[0];
}
/// <summary>
@@ -10,7 +10,7 @@ namespace ZB.MOM.WW.Auth.Ldap;
/// </summary>
/// <remarks>
/// Validation is skipped entirely when <see cref="LdapOptions.Enabled"/> is <c>false</c>
/// (a disabled provider's connection fields are inert). When enabled, four conditions
/// (a disabled provider's connection fields are inert). When enabled, five conditions
/// are enforced:
/// <list type="bullet">
/// <item>plaintext transport (<see cref="LdapTransport.None"/>) is rejected unless
@@ -18,8 +18,13 @@ namespace ZB.MOM.WW.Auth.Ldap;
/// <item><see cref="LdapOptions.Server"/> must be specified (no sane default host);</item>
/// <item><see cref="LdapOptions.SearchBase"/> must be specified (the DN root every
/// search runs against);</item>
/// <item><see cref="LdapOptions.ServiceAccountDn"/> must be specified — an empty value
/// would bind anonymously, defeating the search-then-bind authentication flow.</item>
/// <item>in <see cref="LdapBindMode.ServiceAccount"/> mode <see cref="LdapOptions.ServiceAccountDn"/>
/// must be specified — an empty value would bind anonymously, defeating the search-then-bind
/// authentication flow; in <see cref="LdapBindMode.User"/> mode <see cref="LdapOptions.UserBindTemplate"/>
/// must contain <c>{0}</c> exactly once instead;</item>
/// <item>every <see cref="LdapOptions.FallbackServers"/> entry must parse as
/// <c>"host"</c> or <c>"host:port"</c> — a typo'd backup DC must not lie dormant
/// until the primary outage it exists to survive.</item>
/// </list>
/// </remarks>
public sealed class LdapOptionsValidator : IValidateOptions<LdapOptions>
@@ -60,7 +65,20 @@ public sealed class LdapOptionsValidator : IValidateOptions<LdapOptions>
"set it to the search-base DN (e.g. \"dc=example,dc=com\").");
}
if (string.IsNullOrWhiteSpace(options.ServiceAccountDn))
if (options.BindMode == LdapBindMode.User)
{
// User mode binds as the signing-in user, so there is no service account to require.
// The template is the bind identity: without exactly one {0} every login would bind as
// the same fixed name (or as a name with the user spliced in twice).
if (CountPlaceholders(options.UserBindTemplate) != 1)
{
return ValidateOptionsResult.Fail(
$"{nameof(LdapOptions.UserBindTemplate)} must contain {{0}} exactly once when " +
$"{nameof(LdapOptions.BindMode)} is {nameof(LdapBindMode.User)} — e.g. \"EXAMPLE\\{{0}}\" " +
"(preferred) or \"{0}@example.com\".");
}
}
else if (string.IsNullOrWhiteSpace(options.ServiceAccountDn))
{
return ValidateOptionsResult.Fail(
$"{nameof(LdapOptions.ServiceAccountDn)} is required but was empty or whitespace — " +
@@ -68,6 +86,33 @@ public sealed class LdapOptionsValidator : IValidateOptions<LdapOptions>
"(e.g. \"cn=svc,dc=example,dc=com\").");
}
// Fallback endpoints are walked by LdapAuthService on system-side failures. A
// malformed entry would be silently skipped there (the walk degrades to the
// parseable subset rather than throwing), so it must be caught at boot instead —
// otherwise an operator's typo'd backup DC would only surface as a failed
// failover during the primary outage it was meant to survive.
foreach (var entry in options.FallbackServers)
{
if (!Internal.LdapEndpointParser.TryParse(entry, options.Port, out _, out var error))
{
return ValidateOptionsResult.Fail(
$"{nameof(LdapOptions.FallbackServers)} contains an invalid entry — {error}. " +
"Each entry must be \"host\" or \"host:port\" (port 1–65535).");
}
}
return ValidateOptionsResult.Success;
}
private static int CountPlaceholders(string? template)
{
if (string.IsNullOrEmpty(template))
return 0;
var count = 0;
for (var i = template.IndexOf("{0}", StringComparison.Ordinal); i >= 0;
i = template.IndexOf("{0}", i + 3, StringComparison.Ordinal))
count++;
return count;
}
}
@@ -11,8 +11,8 @@
<PackageId>ZB.MOM.WW.Auth.Ldap</PackageId>
<Authors>ZB.MOM.WW</Authors>
<Description>LDAP authentication service (GLAuth / Active Directory) for the ZB.MOM.WW SCADA family.</Description>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-auth</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-auth</RepositoryUrl>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/scadaproj/src/branch/main/ZB.MOM.WW.Auth</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/scadaproj</RepositoryUrl>
</PropertyGroup>
<ItemGroup>
@@ -22,6 +22,7 @@
<ItemGroup>
<PackageReference Include="Novell.Directory.Ldap.NETStandard" />
<PackageReference Include="Microsoft.Extensions.Options" />
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
</ItemGroup>
<ItemGroup>
@@ -0,0 +1,114 @@
using Microsoft.Data.Sqlite;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests.Live;
/// <summary>
/// Auth-008 (scadaproj#46), the live half: key ids match exactly, as they do in the SQLite store
/// this one ports. The <c>key_id</c> column uses the database's default collation — case-insensitive
/// on a stock SQL Server — so <c>LINE1</c> found the row stored as <c>line1</c>, and the importer
/// counted a SQLite <c>Line1</c> beside <c>line1</c> as an ordinary "skipped" duplicate.
/// </summary>
[Collection("live-sqlserver")]
public sealed class KeyIdFidelityLiveTests : IAsyncLifetime
{
private readonly string _schema = LiveSqlServer.NewSchemaName();
private readonly string _sqlitePath =
Path.Combine(Path.GetTempPath(), $"zbauth-keyid-{Guid.NewGuid():N}.db");
private AuthSqlServerConnectionFactory _factory = null!;
public async Task InitializeAsync()
{
if (!LiveSqlServer.IsEnabled)
return;
_factory = new AuthSqlServerConnectionFactory(LiveSqlServer.OptionsFor(_schema));
await new SqlServerApiKeyStoreMigrator(_factory).MigrateAsync(CancellationToken.None);
}
public async Task DisposeAsync()
{
SqliteConnection.ClearAllPools();
foreach (string path in new[] { _sqlitePath, _sqlitePath + "-wal", _sqlitePath + "-shm" })
{
if (File.Exists(path))
File.Delete(path);
}
await LiveSqlServer.DropSchemaAsync(_schema);
}
private static ApiKeyRecord Record(string keyId) => new(
KeyId: keyId,
KeyPrefix: "sbk",
SecretHash: [1, 2, 3, 4],
DisplayName: "Key " + keyId,
Scopes: new HashSet<string>(["read"], StringComparer.Ordinal),
ConstraintsJson: null,
CreatedUtc: new DateTimeOffset(2026, 5, 1, 8, 30, 0, TimeSpan.Zero),
LastUsedUtc: null,
RevokedUtc: null);
[SkippableFact]
public async Task Lookups_AreCaseSensitive_LikeTheSqliteStore()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
var admin = new SqlServerApiKeyAdminStore(_factory);
var read = new SqlServerApiKeyStore(_factory);
await admin.CreateAsync(Record("line1"), CancellationToken.None);
Assert.NotNull(await read.FindByKeyIdAsync("line1", CancellationToken.None));
Assert.Null(await read.FindByKeyIdAsync("LINE1", CancellationToken.None));
Assert.Null(await read.FindActiveByKeyIdAsync("Line1", CancellationToken.None));
// Trailing spaces are significant too (SQL Server's '=' pads them away).
Assert.Null(await read.FindByKeyIdAsync("line1 ", CancellationToken.None));
Assert.False(await admin.RevokeAsync("LINE1", DateTimeOffset.UtcNow, CancellationToken.None));
Assert.Null((await read.FindByKeyIdAsync("line1", CancellationToken.None))!.RevokedUtc);
}
[SkippableFact]
public async Task Import_CaseVariantKeyIds_AreReportedAsCollisions_NotSkipped()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
var sqliteFactory = new AuthSqliteConnectionFactory(_sqlitePath);
await new SqliteAuthStoreMigrator(sqliteFactory).MigrateAsync(CancellationToken.None);
var sqliteAdmin = new SqliteApiKeyAdminStore(sqliteFactory);
await sqliteAdmin.CreateAsync(Record("line1"), CancellationToken.None);
await sqliteAdmin.CreateAsync(Record("Line1"), CancellationToken.None);
ApiKeyImportResult result = await new SqliteApiKeyStoreImporter(_factory).ImportAsync(_sqlitePath, CancellationToken.None);
Assert.Equal(1, result.KeysInserted);
Assert.Equal(0, result.KeysSkipped);
Assert.Single(result.KeyIdCollisions);
// Re-running: the inserted one is now an ordinary skip, the other still a collision.
ApiKeyImportResult again = await new SqliteApiKeyStoreImporter(_factory).ImportAsync(_sqlitePath, CancellationToken.None);
Assert.Equal(0, again.KeysInserted);
Assert.Equal(1, again.KeysSkipped);
Assert.Single(again.KeyIdCollisions);
}
[SkippableFact]
public async Task Import_OverLengthKey_IsRejected_NotTruncated()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
string longId = new('k', 70);
var sqliteFactory = new AuthSqliteConnectionFactory(_sqlitePath);
await new SqliteAuthStoreMigrator(sqliteFactory).MigrateAsync(CancellationToken.None);
var sqliteAdmin = new SqliteApiKeyAdminStore(sqliteFactory);
await sqliteAdmin.CreateAsync(Record(longId), CancellationToken.None);
await sqliteAdmin.CreateAsync(Record("ok-key"), CancellationToken.None);
ApiKeyImportResult result = await new SqliteApiKeyStoreImporter(_factory).ImportAsync(_sqlitePath, CancellationToken.None);
Assert.Equal(1, result.KeysInserted);
Assert.Equal(longId, Assert.Single(result.KeysRejected));
Assert.Equal(1L, Convert.ToInt64(await LiveSqlServer.ScalarAsync($"SELECT COUNT(*) FROM [{_schema}].[api_keys]")));
}
}
@@ -0,0 +1,101 @@
using Microsoft.Data.SqlClient;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests.Live;
/// <summary>
/// Shared connection details for the env-gated live SQL Server suite.
/// </summary>
/// <remarks>
/// Gated on <c>AUTH_SQLSERVER_CONNSTR</c> and skips cleanly when it is unset, matching the family
/// live-test idiom (see <c>ZB.MOM.WW.Secrets.Replicator.SqlServer</c>) — the offline suite must stay
/// runnable on any machine. Set it to a database the test is allowed to create and drop a schema in,
/// for example <c>Server=localhost,1433;Database=ZbAuthTest;User Id=sa;Password=...;TrustServerCertificate=true</c>.
/// Each test class works in a throwaway <em>schema</em> rather than a throwaway database: it needs no
/// CREATE DATABASE right, and a virgin schema still reproduces the CREATE SCHEMA race the migrator's
/// retry loop exists for.
/// </remarks>
public static class LiveSqlServer
{
/// <summary>Environment variable holding the live connection string.</summary>
public const string ConnectionStringVariable = "AUTH_SQLSERVER_CONNSTR";
/// <summary>The configured connection string, or <see langword="null"/> when the suite is not enabled.</summary>
public static string? ConnectionString =>
Environment.GetEnvironmentVariable(ConnectionStringVariable);
/// <summary>Whether the live suite should run.</summary>
public static bool IsEnabled => !string.IsNullOrWhiteSpace(ConnectionString);
/// <summary>Skip reason shown when the suite is not enabled.</summary>
public const string SkipReason =
"Live SQL Server suite disabled; set AUTH_SQLSERVER_CONNSTR to enable.";
/// <summary>
/// Builds options against a throwaway schema so parallel runs and repeat runs cannot collide,
/// and so a failed run leaves no trace in a shared database.
/// </summary>
/// <param name="schemaName">The unique schema name for this test.</param>
/// <returns>Options targeting that schema.</returns>
public static SqlServerApiKeyOptions OptionsFor(string schemaName) => new()
{
ConnectionString = ConnectionString!,
Schema = schemaName,
};
/// <summary>Generates a unique, allow-list-legal schema name for one test.</summary>
/// <returns>A fresh schema name.</returns>
public static string NewSchemaName() => $"zbauth_test_{Guid.NewGuid():N}"[..32];
/// <summary>Drops the throwaway schema and its three tables.</summary>
/// <param name="schemaName">The schema to drop.</param>
/// <returns>A task that completes when the schema is gone.</returns>
public static async Task DropSchemaAsync(string schemaName)
{
if (!IsEnabled)
{
return;
}
await using var connection = new SqlConnection(ConnectionString);
await connection.OpenAsync();
await using SqlCommand command = connection.CreateCommand();
command.CommandText = $"""
IF OBJECT_ID(N'[{schemaName}].[api_key_audit]', N'U') IS NOT NULL DROP TABLE [{schemaName}].[api_key_audit];
IF OBJECT_ID(N'[{schemaName}].[api_keys]', N'U') IS NOT NULL DROP TABLE [{schemaName}].[api_keys];
IF OBJECT_ID(N'[{schemaName}].[schema_version]', N'U') IS NOT NULL DROP TABLE [{schemaName}].[schema_version];
IF EXISTS (SELECT 1 FROM sys.schemas WHERE name = N'{schemaName}') EXEC(N'DROP SCHEMA [{schemaName}]');
""";
await command.ExecuteNonQueryAsync();
}
/// <summary>Runs a scalar query against the live database.</summary>
/// <param name="commandText">The query text.</param>
/// <returns>The first column of the first row, or <see langword="null"/>.</returns>
public static async Task<object?> ScalarAsync(string commandText)
{
await using var connection = new SqlConnection(ConnectionString);
await connection.OpenAsync();
await using SqlCommand command = connection.CreateCommand();
command.CommandText = commandText;
object? value = await command.ExecuteScalarAsync();
return value == DBNull.Value ? null : value;
}
/// <summary>Runs a non-query statement against the live database.</summary>
/// <param name="commandText">The statement text.</param>
/// <returns>A task that completes when the statement has run.</returns>
public static async Task ExecuteAsync(string commandText)
{
await using var connection = new SqlConnection(ConnectionString);
await connection.OpenAsync();
await using SqlCommand command = connection.CreateCommand();
command.CommandText = commandText;
await command.ExecuteNonQueryAsync();
}
}
@@ -0,0 +1,499 @@
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests.Live;
/// <summary>
/// Live contract tests for <see cref="SqlServerApiKeyAdminStore"/> (and the audit store it is
/// exercised alongside).
/// </summary>
/// <remarks>
/// A one-for-one port of <c>SqliteApiKeyAdminStoreTests</c> — same test names, same assertions — so
/// the create/revoke/rotate/scope/enable/delete semantics are pinned identically across the two
/// providers. xUnit constructs a new test-class instance per test, so each test provisions and drops
/// its own throwaway schema.
/// </remarks>
[Collection("live-sqlserver")]
public sealed class SqlServerApiKeyAdminStoreLiveTests : IAsyncLifetime
{
private readonly string _schema = LiveSqlServer.NewSchemaName();
private AuthSqlServerConnectionFactory _factory = null!;
private SqlServerApiKeyAdminStore _admin = null!;
private SqlServerApiKeyStore _read = null!;
private SqlServerApiKeyAuditStore _audit = null!;
/// <inheritdoc />
public async Task InitializeAsync()
{
if (!LiveSqlServer.IsEnabled)
{
return;
}
_factory = new AuthSqlServerConnectionFactory(LiveSqlServer.OptionsFor(_schema));
await new SqlServerApiKeyStoreMigrator(_factory).MigrateAsync(CancellationToken.None);
_admin = new SqlServerApiKeyAdminStore(_factory);
_read = new SqlServerApiKeyStore(_factory);
_audit = new SqlServerApiKeyAuditStore(_factory);
}
/// <inheritdoc />
public Task DisposeAsync() => LiveSqlServer.DropSchemaAsync(_schema);
// --- Create ---
[SkippableFact]
public async Task Create_ThenFindByKeyId_ReturnsRecord()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
ApiKeyRecord record = SampleRecord("key-1");
await _admin.CreateAsync(record, CancellationToken.None);
ApiKeyRecord? found = await _read.FindByKeyIdAsync("key-1", CancellationToken.None);
Assert.NotNull(found);
Assert.Equal(record.SecretHash, found!.SecretHash);
Assert.True(record.Scopes.SetEquals(found.Scopes));
Assert.Equal(record.ConstraintsJson, found.ConstraintsJson);
Assert.Null(found.LastUsedUtc);
Assert.Null(found.RevokedUtc);
}
[SkippableFact]
public async Task Create_WithExpiresUtc_RoundTripsThroughFindAndList()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
var expiry = new DateTimeOffset(2026, 12, 31, 23, 59, 59, TimeSpan.Zero);
ApiKeyRecord record = SampleRecord("key-exp") with { ExpiresUtc = expiry };
await _admin.CreateAsync(record, CancellationToken.None);
ApiKeyRecord? found = await _read.FindByKeyIdAsync("key-exp", CancellationToken.None);
Assert.Equal(expiry, found!.ExpiresUtc);
IReadOnlyList<ApiKeyListItem> listed = await _admin.ListAsync(CancellationToken.None);
ApiKeyListItem item = Assert.Single(listed, k => k.KeyId == "key-exp");
Assert.Equal(expiry, item.ExpiresUtc);
}
[SkippableFact]
public async Task Create_WithoutExpiresUtc_ReadsBackAsNull()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
ApiKeyRecord? found = await _read.FindByKeyIdAsync("key-1", CancellationToken.None);
Assert.Null(found!.ExpiresUtc);
IReadOnlyList<ApiKeyListItem> listed = await _admin.ListAsync(CancellationToken.None);
Assert.Null(Assert.Single(listed, k => k.KeyId == "key-1").ExpiresUtc);
}
// --- Revoke ---
[SkippableFact]
public async Task Revoke_ActiveKey_SetsRevokedAndFindActiveReturnsNull()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
var when = new DateTimeOffset(2026, 5, 31, 9, 0, 0, TimeSpan.Zero);
bool result = await _admin.RevokeAsync("key-1", when, CancellationToken.None);
Assert.True(result);
Assert.Null(await _read.FindActiveByKeyIdAsync("key-1", CancellationToken.None));
ApiKeyRecord? found = await _read.FindByKeyIdAsync("key-1", CancellationToken.None);
Assert.Equal(when, found!.RevokedUtc);
}
[SkippableFact]
public async Task Revoke_UnknownKey_ReturnsFalse()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
bool result = await _admin.RevokeAsync("missing", DateTimeOffset.UtcNow, CancellationToken.None);
Assert.False(result);
}
[SkippableFact]
public async Task Revoke_AlreadyRevoked_ReturnsFalse()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
await _admin.RevokeAsync("key-1", DateTimeOffset.UtcNow, CancellationToken.None);
bool result = await _admin.RevokeAsync("key-1", DateTimeOffset.UtcNow, CancellationToken.None);
Assert.False(result);
}
// --- Rotate ---
[SkippableFact]
public async Task Rotate_ChangesHashAndReactivates()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
await _admin.RevokeAsync("key-1", DateTimeOffset.UtcNow, CancellationToken.None);
await _read.MarkUsedAsync("key-1", DateTimeOffset.UtcNow, CancellationToken.None);
byte[] newHash = [9, 9, 9, 9];
bool result = await _admin.RotateAsync("key-1", newHash, CancellationToken.None);
Assert.True(result);
ApiKeyRecord? found = await _read.FindByKeyIdAsync("key-1", CancellationToken.None);
Assert.Equal(newHash, found!.SecretHash);
Assert.Null(found.RevokedUtc);
Assert.Null(found.LastUsedUtc);
// Reactivated: now visible as active.
Assert.NotNull(await _read.FindActiveByKeyIdAsync("key-1", CancellationToken.None));
}
[SkippableFact]
public async Task Rotate_UnknownKey_ReturnsFalse()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
bool result = await _admin.RotateAsync("missing", [1], CancellationToken.None);
Assert.False(result);
}
// --- SetScopes ---
[SkippableFact]
public async Task SetScopesAsync_ReplacesScopes_AndReturnsTrue()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _admin.CreateAsync(
SampleRecord("key-1") with { Scopes = new HashSet<string>(["a"], StringComparer.Ordinal) },
CancellationToken.None);
bool result = await _admin.SetScopesAsync(
"key-1",
new HashSet<string>(["b", "c"], StringComparer.Ordinal),
CancellationToken.None);
Assert.True(result);
IReadOnlyList<ApiKeyListItem> listed = await _admin.ListAsync(CancellationToken.None);
ApiKeyListItem item = Assert.Single(listed, k => k.KeyId == "key-1");
Assert.True(item.Scopes.SetEquals(new HashSet<string>(["b", "c"], StringComparer.Ordinal)));
}
[SkippableFact]
public async Task SetScopesAsync_UnknownKey_ReturnsFalse()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
bool result = await _admin.SetScopesAsync(
"missing",
new HashSet<string>(["b"], StringComparer.Ordinal),
CancellationToken.None);
Assert.False(result);
}
// --- SetEnabled ---
[SkippableFact]
public async Task SetEnabledAsync_False_DisablesKey()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
var when = new DateTimeOffset(2026, 5, 31, 9, 0, 0, TimeSpan.Zero);
bool result = await _admin.SetEnabledAsync("key-1", enabled: false, when, CancellationToken.None);
Assert.True(result);
Assert.Null(await _read.FindActiveByKeyIdAsync("key-1", CancellationToken.None));
ApiKeyRecord? found = await _read.FindByKeyIdAsync("key-1", CancellationToken.None);
Assert.Equal(when, found!.RevokedUtc);
}
[SkippableFact]
public async Task SetEnabledAsync_True_ReenablesKey_WithoutChangingSecret()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
ApiKeyRecord original = SampleRecord("key-1");
await _admin.CreateAsync(original, CancellationToken.None);
// Record some usage so we can prove last_used_utc is left untouched on re-enable.
var used = new DateTimeOffset(2026, 5, 20, 12, 0, 0, TimeSpan.Zero);
await _read.MarkUsedAsync("key-1", used, CancellationToken.None);
// Disable, then re-enable.
await _admin.SetEnabledAsync(
"key-1", enabled: false, new DateTimeOffset(2026, 5, 31, 9, 0, 0, TimeSpan.Zero), CancellationToken.None);
bool result = await _admin.SetEnabledAsync(
"key-1", enabled: true, new DateTimeOffset(2026, 6, 1, 9, 0, 0, TimeSpan.Zero), CancellationToken.None);
Assert.True(result);
// Active again, and the secret hash + last-used timestamp are unchanged.
ApiKeyRecord? active = await _read.FindActiveByKeyIdAsync("key-1", CancellationToken.None);
Assert.NotNull(active);
Assert.True(active!.SecretHash.SequenceEqual(original.SecretHash));
Assert.Null(active.RevokedUtc);
Assert.Equal(used, active.LastUsedUtc);
}
[SkippableFact]
public async Task SetEnabledAsync_UnknownKey_ReturnsFalse()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
bool result = await _admin.SetEnabledAsync(
"missing", enabled: false, DateTimeOffset.UtcNow, CancellationToken.None);
Assert.False(result);
}
// --- Delete ---
[SkippableFact]
public async Task Delete_ActiveKey_ReturnsFalseAndKeyStillPresent()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
bool result = await _admin.DeleteAsync("key-1", CancellationToken.None);
Assert.False(result);
Assert.NotNull(await _read.FindByKeyIdAsync("key-1", CancellationToken.None));
}
[SkippableFact]
public async Task Delete_RevokedKey_ReturnsTrueAndKeyGone()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
await _admin.RevokeAsync("key-1", DateTimeOffset.UtcNow, CancellationToken.None);
bool result = await _admin.DeleteAsync("key-1", CancellationToken.None);
Assert.True(result);
Assert.Null(await _read.FindByKeyIdAsync("key-1", CancellationToken.None));
}
[SkippableFact]
public async Task Delete_UnknownKey_ReturnsFalse()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
bool result = await _admin.DeleteAsync("missing", CancellationToken.None);
Assert.False(result);
}
// --- keyId guard tests ---
[SkippableTheory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public async Task Revoke_NullOrWhitespaceKeyId_ThrowsArgumentException(string? keyId)
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
// ArgumentNullException (null) and ArgumentException (empty/whitespace) are both acceptable;
// ThrowIfNullOrWhiteSpace throws ArgumentNullException for null, ArgumentException for whitespace.
await Assert.ThrowsAnyAsync<ArgumentException>(
() => _admin.RevokeAsync(keyId!, DateTimeOffset.UtcNow, CancellationToken.None));
}
[SkippableTheory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public async Task Rotate_NullOrWhitespaceKeyId_ThrowsArgumentException(string? keyId)
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await Assert.ThrowsAnyAsync<ArgumentException>(
() => _admin.RotateAsync(keyId!, [1, 2, 3], CancellationToken.None));
}
[SkippableTheory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public async Task Delete_NullOrWhitespaceKeyId_ThrowsArgumentException(string? keyId)
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await Assert.ThrowsAnyAsync<ArgumentException>(
() => _admin.DeleteAsync(keyId!, CancellationToken.None));
}
[SkippableTheory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public async Task SetScopesAsync_NullOrWhitespaceKeyId_ThrowsArgumentException(string? keyId)
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await Assert.ThrowsAnyAsync<ArgumentException>(
() => _admin.SetScopesAsync(
keyId!,
new HashSet<string>(["read"], StringComparer.Ordinal),
CancellationToken.None));
}
[SkippableTheory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public async Task SetEnabledAsync_NullOrWhitespaceKeyId_ThrowsArgumentException(string? keyId)
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await Assert.ThrowsAnyAsync<ArgumentException>(
() => _admin.SetEnabledAsync(keyId!, enabled: false, DateTimeOffset.UtcNow, CancellationToken.None));
}
[SkippableFact]
public async Task SetScopesAsync_NullScopes_ThrowsArgumentNullException()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
await Assert.ThrowsAsync<ArgumentNullException>(
() => _admin.SetScopesAsync("key-1", null!, CancellationToken.None));
}
// --- SetEnabled idempotence ---
[SkippableFact]
public async Task SetEnabledAsync_OnAlreadyActiveKey_ReturnsTrue()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
bool result = await _admin.SetEnabledAsync(
"key-1", enabled: true, DateTimeOffset.UtcNow, CancellationToken.None);
Assert.True(result);
ApiKeyRecord? active = await _read.FindActiveByKeyIdAsync("key-1", CancellationToken.None);
Assert.NotNull(active);
Assert.Null(active!.RevokedUtc);
}
[SkippableFact]
public async Task SetEnabledAsync_OnAlreadyDisabledKey_OverwritesTimestamp_ReturnsTrue()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
var t1 = new DateTimeOffset(2026, 5, 1, 10, 0, 0, TimeSpan.Zero);
var t2 = new DateTimeOffset(2026, 5, 15, 10, 0, 0, TimeSpan.Zero);
// Disable at t1.
await _admin.SetEnabledAsync("key-1", enabled: false, t1, CancellationToken.None);
// Disable again at a later t2 (idempotent overwrite — no guard on revoked_utc).
bool result = await _admin.SetEnabledAsync("key-1", enabled: false, t2, CancellationToken.None);
Assert.True(result);
IReadOnlyList<ApiKeyListItem> listed = await _admin.ListAsync(CancellationToken.None);
ApiKeyListItem item = Assert.Single(listed, k => k.KeyId == "key-1");
Assert.Equal(t2, item.RevokedUtc);
}
// --- Audit ---
[SkippableFact]
public async Task Audit_AppendThenListRecent_ReturnsEntry()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
var entry = new ApiKeyAuditEntry(
KeyId: "key-1",
EventType: "created",
RemoteAddress: "10.0.0.1",
CreatedUtc: new DateTimeOffset(2026, 5, 31, 10, 0, 0, TimeSpan.Zero),
Details: "by admin");
await _audit.AppendAsync(entry, CancellationToken.None);
IReadOnlyList<ApiKeyAuditEntry> recent = await _audit.ListRecentAsync(10, CancellationToken.None);
Assert.Single(recent);
Assert.Equal("key-1", recent[0].KeyId);
Assert.Equal("created", recent[0].EventType);
Assert.Equal("10.0.0.1", recent[0].RemoteAddress);
Assert.Equal("by admin", recent[0].Details);
}
[SkippableFact]
public async Task Audit_ListRecent_ReturnsNewestFirst()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _audit.AppendAsync(
new ApiKeyAuditEntry("k", "first", null, DateTimeOffset.UtcNow, null), CancellationToken.None);
await _audit.AppendAsync(
new ApiKeyAuditEntry("k", "second", null, DateTimeOffset.UtcNow, null), CancellationToken.None);
await _audit.AppendAsync(
new ApiKeyAuditEntry("k", "third", null, DateTimeOffset.UtcNow, null), CancellationToken.None);
IReadOnlyList<ApiKeyAuditEntry> recent = await _audit.ListRecentAsync(10, CancellationToken.None);
Assert.Equal(["third", "second", "first"], recent.Select(e => e.EventType));
}
[SkippableFact]
public async Task Audit_ListRecent_RespectsLimit()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
for (int i = 0; i < 5; i++)
{
await _audit.AppendAsync(
new ApiKeyAuditEntry("k", $"e{i}", null, DateTimeOffset.UtcNow, null), CancellationToken.None);
}
IReadOnlyList<ApiKeyAuditEntry> recent = await _audit.ListRecentAsync(2, CancellationToken.None);
Assert.Equal(2, recent.Count);
Assert.Equal(["e4", "e3"], recent.Select(e => e.EventType));
}
[SkippableFact]
public async Task Audit_NullableFields_RoundTripAsNull()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _audit.AppendAsync(
new ApiKeyAuditEntry(null, "anon", null, DateTimeOffset.UtcNow, null), CancellationToken.None);
IReadOnlyList<ApiKeyAuditEntry> recent = await _audit.ListRecentAsync(10, CancellationToken.None);
Assert.Single(recent);
Assert.Null(recent[0].KeyId);
Assert.Null(recent[0].RemoteAddress);
Assert.Null(recent[0].Details);
}
private static ApiKeyRecord SampleRecord(string keyId) => new(
KeyId: keyId,
KeyPrefix: "mxgw_ab12",
SecretHash: [1, 2, 3, 4, 5, 6, 7, 8],
DisplayName: "Test Key " + keyId,
Scopes: new HashSet<string>(["read", "write"], StringComparer.Ordinal),
ConstraintsJson: """{"ipAllow":["10.0.0.0/8"]}""",
CreatedUtc: new DateTimeOffset(2026, 5, 1, 8, 30, 0, TimeSpan.Zero),
LastUsedUtc: null,
RevokedUtc: null);
}
@@ -0,0 +1,74 @@
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests.Live;
/// <summary>
/// Live tests for <see cref="SqlServerApiKeyAuditStore"/> that the ported SQLite suite does not
/// already cover: newest-first ordering under a limit, and the non-positive-limit short circuit.
/// </summary>
/// <remarks>
/// xUnit constructs a new test-class instance per test, so each test provisions and drops its own
/// throwaway schema.
/// </remarks>
[Collection("live-sqlserver")]
public sealed class SqlServerApiKeyAuditStoreLiveTests : IAsyncLifetime
{
private readonly string _schema = LiveSqlServer.NewSchemaName();
private SqlServerApiKeyAuditStore _audit = null!;
/// <inheritdoc />
public async Task InitializeAsync()
{
if (!LiveSqlServer.IsEnabled)
{
return;
}
var factory = new AuthSqlServerConnectionFactory(LiveSqlServer.OptionsFor(_schema));
await new SqlServerApiKeyStoreMigrator(factory).MigrateAsync(CancellationToken.None);
_audit = new SqlServerApiKeyAuditStore(factory);
}
/// <inheritdoc />
public Task DisposeAsync() => LiveSqlServer.DropSchemaAsync(_schema);
[SkippableFact]
public async Task Append_ThenListRecent_ReturnsNewestFirstWithinLimit()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
// Every row carries the SAME created_utc, so the newest-first order can only come from the
// IDENTITY audit_id the ORDER BY names — the timestamp cannot accidentally supply it.
var when = new DateTimeOffset(2026, 7, 1, 0, 0, 0, TimeSpan.Zero);
for (int i = 0; i < 6; i++)
{
await _audit.AppendAsync(
new ApiKeyAuditEntry("k", $"e{i}", "10.0.0.1", when, $"detail {i}"),
CancellationToken.None);
}
IReadOnlyList<ApiKeyAuditEntry> recent = await _audit.ListRecentAsync(3, CancellationToken.None);
Assert.Equal(3, recent.Count);
Assert.Equal(["e5", "e4", "e3"], recent.Select(e => e.EventType));
Assert.Equal("detail 5", recent[0].Details);
Assert.Equal(when, recent[0].CreatedUtc);
}
[SkippableFact]
public async Task ListRecent_NonPositiveLimit_ReturnsEmpty()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await _audit.AppendAsync(
new ApiKeyAuditEntry("k", "created", null, DateTimeOffset.UtcNow, null),
CancellationToken.None);
// A non-positive limit short circuits WITHOUT touching the database — SELECT TOP (0) would
// be legal but SELECT TOP (-1) is a syntax error, so the guard is load-bearing here in a way
// it is not for SQLite's LIMIT.
Assert.Empty(await _audit.ListRecentAsync(0, CancellationToken.None));
Assert.Empty(await _audit.ListRecentAsync(-5, CancellationToken.None));
}
}
@@ -0,0 +1,340 @@
using System.Data;
using Microsoft.Data.SqlClient;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests.Live;
/// <summary>
/// Live contract tests for <see cref="SqlServerApiKeyStore"/>.
/// </summary>
/// <remarks>
/// A one-for-one port of <c>SqliteApiKeyStoreTests</c> (same test names, same assertions) so the two
/// providers are pinned to identical semantics: whichever store a host composes, a row means the
/// same thing. xUnit constructs a new test-class instance per test, so each test provisions and
/// drops its own throwaway schema — the isolation the SQLite suite gets from a per-test temp file.
/// </remarks>
[Collection("live-sqlserver")]
public sealed class SqlServerApiKeyStoreLiveTests : IAsyncLifetime
{
private readonly string _schema = LiveSqlServer.NewSchemaName();
private AuthSqlServerConnectionFactory _factory = null!;
private SqlServerApiKeyStore _store = null!;
/// <inheritdoc />
public async Task InitializeAsync()
{
if (!LiveSqlServer.IsEnabled)
{
return;
}
_factory = new AuthSqlServerConnectionFactory(LiveSqlServer.OptionsFor(_schema));
await new SqlServerApiKeyStoreMigrator(_factory).MigrateAsync(CancellationToken.None);
_store = new SqlServerApiKeyStore(_factory);
}
/// <inheritdoc />
public Task DisposeAsync() => LiveSqlServer.DropSchemaAsync(_schema);
[SkippableFact]
public async Task FindByKeyId_AfterInsert_ReturnsEqualRecord()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
ApiKeyRecord record = SampleRecord("key-1");
await InsertAsync(record);
ApiKeyRecord? found = await _store.FindByKeyIdAsync("key-1", CancellationToken.None);
Assert.NotNull(found);
AssertRecordEqual(record, found!);
}
[SkippableFact]
public async Task FindByKeyId_ReturnsRevokedRecord()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
ApiKeyRecord record = SampleRecord("key-revoked") with
{
RevokedUtc = new DateTimeOffset(2026, 1, 2, 3, 4, 5, TimeSpan.Zero),
};
await InsertAsync(record);
ApiKeyRecord? found = await _store.FindByKeyIdAsync("key-revoked", CancellationToken.None);
Assert.NotNull(found);
Assert.NotNull(found!.RevokedUtc);
}
[SkippableFact]
public async Task FindActiveByKeyId_RevokedKey_ReturnsNull()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
ApiKeyRecord record = SampleRecord("key-revoked") with
{
RevokedUtc = new DateTimeOffset(2026, 1, 2, 3, 4, 5, TimeSpan.Zero),
};
await InsertAsync(record);
ApiKeyRecord? found = await _store.FindActiveByKeyIdAsync("key-revoked", CancellationToken.None);
Assert.Null(found);
}
[SkippableFact]
public async Task FindActiveByKeyId_ActiveKey_ReturnsRecord()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await InsertAsync(SampleRecord("key-active"));
ApiKeyRecord? found = await _store.FindActiveByKeyIdAsync("key-active", CancellationToken.None);
Assert.NotNull(found);
}
[SkippableFact]
public async Task FindByKeyId_UnknownKey_ReturnsNull()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
ApiKeyRecord? found = await _store.FindByKeyIdAsync("missing", CancellationToken.None);
Assert.Null(found);
}
[SkippableFact]
public async Task MarkUsed_ActiveKey_UpdatesLastUsed()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await InsertAsync(SampleRecord("key-active"));
var when = new DateTimeOffset(2026, 5, 31, 12, 0, 0, TimeSpan.Zero);
await _store.MarkUsedAsync("key-active", when, CancellationToken.None);
ApiKeyRecord? found = await _store.FindByKeyIdAsync("key-active", CancellationToken.None);
Assert.Equal(when, found!.LastUsedUtc);
}
[SkippableFact]
public async Task MarkUsed_RevokedKey_DoesNotUpdateLastUsed()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
ApiKeyRecord record = SampleRecord("key-revoked") with
{
RevokedUtc = new DateTimeOffset(2026, 1, 2, 3, 4, 5, TimeSpan.Zero),
};
await InsertAsync(record);
var when = new DateTimeOffset(2026, 5, 31, 12, 0, 0, TimeSpan.Zero);
await _store.MarkUsedAsync("key-revoked", when, CancellationToken.None);
ApiKeyRecord? found = await _store.FindByKeyIdAsync("key-revoked", CancellationToken.None);
Assert.Null(found!.LastUsedUtc);
}
// --- SQL-Server-specific: DATETIMEOFFSET(7) must not truncate to milliseconds ---
[SkippableFact]
public async Task FindByKeyId_RoundTripsDateTimeOffsetToTheTick()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
// Sub-millisecond ticks: SQLite persists round-trip ("O") text and keeps them for free,
// whereas SQL Server keeps them only because the columns are DATETIMEOFFSET(7) and the
// parameters are bound as SqlDbType.DateTimeOffset. A DATETIME/DATETIME2(3) column or an
// untyped parameter would silently round here.
var created = new DateTimeOffset(2026, 3, 4, 5, 6, 7, TimeSpan.Zero).AddTicks(1234567);
var expires = new DateTimeOffset(2027, 3, 4, 5, 6, 7, TimeSpan.Zero).AddTicks(7654321);
ApiKeyRecord record = SampleRecord("key-ticks") with { CreatedUtc = created, ExpiresUtc = expires };
await InsertAsync(record);
ApiKeyRecord? found = await _store.FindByKeyIdAsync("key-ticks", CancellationToken.None);
Assert.NotNull(found);
Assert.Equal(created, found!.CreatedUtc);
Assert.Equal(created.Ticks, found.CreatedUtc.Ticks);
Assert.Equal(expires, found.ExpiresUtc);
Assert.Equal(expires.Ticks, found.ExpiresUtc!.Value.Ticks);
}
// --- keyId guard tests ---
[SkippableTheory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public async Task FindByKeyId_NullOrWhitespaceKeyId_ThrowsArgumentException(string? keyId)
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
// ArgumentNullException (null) and ArgumentException (empty/whitespace) are both acceptable;
// ThrowIfNullOrWhiteSpace throws ArgumentNullException for null, ArgumentException for whitespace.
await Assert.ThrowsAnyAsync<ArgumentException>(
() => _store.FindByKeyIdAsync(keyId!, CancellationToken.None));
}
[SkippableTheory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public async Task FindActiveByKeyId_NullOrWhitespaceKeyId_ThrowsArgumentException(string? keyId)
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await Assert.ThrowsAnyAsync<ArgumentException>(
() => _store.FindActiveByKeyIdAsync(keyId!, CancellationToken.None));
}
[SkippableTheory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public async Task MarkUsed_NullOrWhitespaceKeyId_ThrowsArgumentException(string? keyId)
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await Assert.ThrowsAnyAsync<ArgumentException>(
() => _store.MarkUsedAsync(keyId!, DateTimeOffset.UtcNow, CancellationToken.None));
}
[SkippableFact]
public void ScopeSerializer_RoundTripsAndSortsOrdinally()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
var unsorted = new HashSet<string>(["zeta", "alpha", "mike"], StringComparer.Ordinal);
var differentOrder = new HashSet<string>(["mike", "zeta", "alpha"], StringComparer.Ordinal);
string a = ScopeSerializer.Serialize(unsorted);
string b = ScopeSerializer.Serialize(differentOrder);
// Equal sets must produce identical column text regardless of insertion order.
Assert.Equal(a, b);
Assert.Equal("""["alpha","mike","zeta"]""", a);
IReadOnlySet<string> roundTripped = ScopeSerializer.Deserialize(a);
Assert.True(roundTripped.SetEquals(unsorted));
}
[SkippableFact]
public void ScopeSerializer_DeserializeNullOrEmpty_ReturnsEmptySet()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
Assert.Empty(ScopeSerializer.Deserialize(null));
Assert.Empty(ScopeSerializer.Deserialize(""));
}
// --- Auth-003: corrupt scopes JSON must fail closed (empty set), never throw JsonException ---
[SkippableTheory]
[InlineData("not json at all")]
[InlineData("{")]
[InlineData("{\"a\":1}")] // valid JSON, but an object, not a string[]
[InlineData("42")] // valid JSON, but a number
[InlineData("[\"read\",")] // truncated/partial write
public void ScopeSerializer_DeserializeMalformed_ReturnsEmptySet_DoesNotThrow(string value)
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
// A poisoned scopes column (tampering, partial write, format change, buggy writer) must
// degrade to a zero-scope set rather than throwing on the verification hot path.
IReadOnlySet<string> scopes = ScopeSerializer.Deserialize(value);
Assert.Empty(scopes);
}
[SkippableFact]
public async Task FindByKeyId_CorruptScopesColumn_ReturnsRecordWithEmptyScopes_DoesNotThrow()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
// Insert a row whose scopes column holds malformed (non-array) JSON, then read it through
// the store. The store must NOT propagate a JsonException out of FindByKeyIdAsync (which the
// verifier relies on for its "only exception path is cancellation" contract).
await InsertWithRawScopesAsync("key-corrupt", scopesJson: "{ this is not valid json");
ApiKeyRecord? found = await _store.FindByKeyIdAsync("key-corrupt", CancellationToken.None);
Assert.NotNull(found);
Assert.Empty(found!.Scopes);
}
private static ApiKeyRecord SampleRecord(string keyId) => new(
KeyId: keyId,
KeyPrefix: "mxgw_ab12",
SecretHash: [1, 2, 3, 4, 5, 6, 7, 8],
DisplayName: "Test Key " + keyId,
Scopes: new HashSet<string>(["read", "write"], StringComparer.Ordinal),
ConstraintsJson: """{"ipAllow":["10.0.0.0/8"]}""",
CreatedUtc: new DateTimeOffset(2026, 5, 1, 8, 30, 0, TimeSpan.Zero),
LastUsedUtc: null,
RevokedUtc: null);
private static void AssertRecordEqual(ApiKeyRecord expected, ApiKeyRecord actual)
{
Assert.Equal(expected.KeyId, actual.KeyId);
Assert.Equal(expected.KeyPrefix, actual.KeyPrefix);
Assert.Equal(expected.SecretHash, actual.SecretHash);
Assert.Equal(expected.DisplayName, actual.DisplayName);
Assert.True(expected.Scopes.SetEquals(actual.Scopes));
Assert.Equal(expected.ConstraintsJson, actual.ConstraintsJson);
Assert.Equal(expected.CreatedUtc, actual.CreatedUtc);
Assert.Equal(expected.LastUsedUtc, actual.LastUsedUtc);
Assert.Equal(expected.RevokedUtc, actual.RevokedUtc);
}
private async Task InsertAsync(ApiKeyRecord record)
{
await using SqlConnection connection =
await _factory.OpenConnectionAsync(CancellationToken.None);
await using SqlCommand command = _factory.CreateCommand(connection, $"""
INSERT INTO [{_schema}].[{SqlServerAuthSchema.ApiKeysTable}] (
key_id, key_prefix, secret_hash, display_name, scopes,
constraints, created_utc, last_used_utc, revoked_utc, expires_utc)
VALUES (
@key_id, @key_prefix, @secret_hash, @display_name, @scopes,
@constraints, @created_utc, @last_used_utc, @revoked_utc, @expires_utc);
""");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = record.KeyId;
command.Parameters.Add("@key_prefix", SqlDbType.NVarChar, 16).Value = record.KeyPrefix;
command.Parameters.Add("@secret_hash", SqlDbType.VarBinary, 64).Value = record.SecretHash;
command.Parameters.Add("@display_name", SqlDbType.NVarChar, 256).Value = record.DisplayName;
command.Parameters.Add("@scopes", SqlDbType.NVarChar, -1).Value = ScopeSerializer.Serialize(record.Scopes);
command.Parameters.Add("@constraints", SqlDbType.NVarChar, -1).Value = (object?)record.ConstraintsJson ?? DBNull.Value;
command.Parameters.Add("@created_utc", SqlDbType.DateTimeOffset).Value = record.CreatedUtc;
command.Parameters.Add("@last_used_utc", SqlDbType.DateTimeOffset).Value = (object?)record.LastUsedUtc ?? DBNull.Value;
command.Parameters.Add("@revoked_utc", SqlDbType.DateTimeOffset).Value = (object?)record.RevokedUtc ?? DBNull.Value;
command.Parameters.Add("@expires_utc", SqlDbType.DateTimeOffset).Value = (object?)record.ExpiresUtc ?? DBNull.Value;
await command.ExecuteNonQueryAsync(CancellationToken.None);
}
private async Task InsertWithRawScopesAsync(string keyId, string scopesJson)
{
// Writes the scopes column verbatim (NOT via ScopeSerializer.Serialize) so a malformed
// value can be persisted to simulate tampering / a partial or buggy write.
await using SqlConnection connection =
await _factory.OpenConnectionAsync(CancellationToken.None);
await using SqlCommand command = _factory.CreateCommand(connection, $"""
INSERT INTO [{_schema}].[{SqlServerAuthSchema.ApiKeysTable}] (
key_id, key_prefix, secret_hash, display_name, scopes,
constraints, created_utc, last_used_utc, revoked_utc, expires_utc)
VALUES (
@key_id, @key_prefix, @secret_hash, @display_name, @scopes,
NULL, @created_utc, NULL, NULL, NULL);
""");
command.Parameters.Add("@key_id", SqlDbType.NVarChar, 64).Value = keyId;
command.Parameters.Add("@key_prefix", SqlDbType.NVarChar, 16).Value = "mxgw";
command.Parameters.Add("@secret_hash", SqlDbType.VarBinary, 64).Value = new byte[] { 1, 2, 3 };
command.Parameters.Add("@display_name", SqlDbType.NVarChar, 256).Value = "Corrupt Key";
command.Parameters.Add("@scopes", SqlDbType.NVarChar, -1).Value = scopesJson;
command.Parameters.Add("@created_utc", SqlDbType.DateTimeOffset).Value = DateTimeOffset.UnixEpoch;
await command.ExecuteNonQueryAsync(CancellationToken.None);
}
}
@@ -0,0 +1,145 @@
using System.Globalization;
using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests.Live;
/// <summary>
/// Live provisioning tests for <see cref="SqlServerApiKeyStoreMigrator"/>.
/// </summary>
/// <remarks>
/// Every test provisions its own throwaway schema — the concurrency case in particular needs a
/// virgin one, because the race the retry loop exists for only happens while the schema and tables
/// do not yet exist. All schemas created by the class are dropped in <see cref="DisposeAsync"/>.
/// </remarks>
[Collection("live-sqlserver")]
public sealed class SqlServerApiKeyStoreMigratorLiveTests : IAsyncLifetime
{
private readonly List<string> _schemas = [];
/// <inheritdoc />
public Task InitializeAsync() => Task.CompletedTask;
/// <inheritdoc />
public async Task DisposeAsync()
{
foreach (string schema in _schemas)
{
await LiveSqlServer.DropSchemaAsync(schema);
}
}
private string NewSchema()
{
string schema = LiveSqlServer.NewSchemaName();
_schemas.Add(schema);
return schema;
}
private static SqlServerApiKeyStoreMigrator MigratorFor(string schema) =>
new(new AuthSqlServerConnectionFactory(LiveSqlServer.OptionsFor(schema)));
[SkippableFact]
public async Task Migrate_OnEmptyDatabase_CreatesSchemaTablesAndVersionRow()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
string schema = NewSchema();
await MigratorFor(schema).MigrateAsync(CancellationToken.None);
Assert.Equal(
1,
Convert.ToInt32(
await LiveSqlServer.ScalarAsync(
$"SELECT COUNT(*) FROM sys.schemas WHERE name = N'{schema}'"),
CultureInfo.InvariantCulture));
foreach (string table in new[]
{
SqlServerAuthSchema.SchemaVersionTable,
SqlServerAuthSchema.ApiKeysTable,
SqlServerAuthSchema.ApiKeyAuditTable,
})
{
Assert.NotNull(
await LiveSqlServer.ScalarAsync($"SELECT OBJECT_ID(N'[{schema}].[{table}]', N'U')"));
}
Assert.Equal(
SqlServerAuthSchema.CurrentVersion,
Convert.ToInt32(
await LiveSqlServer.ScalarAsync(
$"SELECT version FROM [{schema}].[{SqlServerAuthSchema.SchemaVersionTable}] WHERE id = 1"),
CultureInfo.InvariantCulture));
}
[SkippableFact]
public async Task Migrate_Twice_IsIdempotent()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
string schema = NewSchema();
SqlServerApiKeyStoreMigrator migrator = MigratorFor(schema);
await migrator.MigrateAsync(CancellationToken.None);
await migrator.MigrateAsync(CancellationToken.None);
Assert.Equal(
1,
Convert.ToInt32(
await LiveSqlServer.ScalarAsync(
$"SELECT COUNT(*) FROM [{schema}].[{SqlServerAuthSchema.SchemaVersionTable}]"),
CultureInfo.InvariantCulture));
Assert.Equal(
SqlServerAuthSchema.CurrentVersion,
Convert.ToInt32(
await LiveSqlServer.ScalarAsync(
$"SELECT version FROM [{schema}].[{SqlServerAuthSchema.SchemaVersionTable}] WHERE id = 1"),
CultureInfo.InvariantCulture));
}
[SkippableFact]
public async Task Migrate_Concurrently_FromEightTasks_AllSucceed()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
// A virgin schema provisioned by eight nodes at once — the central-pair first boot, scaled
// up. Each task gets its own factory (and therefore its own connection) so the DDL really
// does run on eight sessions.
string schema = NewSchema();
await Task.WhenAll(Enumerable.Range(0, 8).Select(_ =>
Task.Run(() => MigratorFor(schema).MigrateAsync(CancellationToken.None))));
Assert.Equal(
1,
Convert.ToInt32(
await LiveSqlServer.ScalarAsync(
$"SELECT COUNT(*) FROM [{schema}].[{SqlServerAuthSchema.SchemaVersionTable}]"),
CultureInfo.InvariantCulture));
Assert.Equal(
SqlServerAuthSchema.CurrentVersion,
Convert.ToInt32(
await LiveSqlServer.ScalarAsync(
$"SELECT version FROM [{schema}].[{SqlServerAuthSchema.SchemaVersionTable}] WHERE id = 1"),
CultureInfo.InvariantCulture));
}
[SkippableFact]
public async Task Migrate_WhenStoredVersionIsNewer_Throws()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
string schema = NewSchema();
SqlServerApiKeyStoreMigrator migrator = MigratorFor(schema);
await migrator.MigrateAsync(CancellationToken.None);
await LiveSqlServer.ExecuteAsync(
$"UPDATE [{schema}].[{SqlServerAuthSchema.SchemaVersionTable}] SET version = 99 WHERE id = 1");
AuthStoreMigrationException exception = await Assert.ThrowsAsync<AuthStoreMigrationException>(
() => migrator.MigrateAsync(CancellationToken.None));
Assert.Contains("99", exception.Message, StringComparison.Ordinal);
}
}
@@ -0,0 +1,283 @@
using Microsoft.Data.Sqlite;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests.Live;
/// <summary>
/// Live tests for <see cref="SqliteApiKeyStoreImporter"/> — the one-shot per-node SQLite to shared
/// SQL Server copy.
/// </summary>
/// <remarks>
/// Each test owns a throwaway SQL Server schema AND a throwaway SQLite file under the temp
/// directory; both are torn down in <see cref="DisposeAsync"/>, so a failed run leaves nothing
/// behind on a shared database or the developer's disk.
/// </remarks>
[Collection("live-sqlserver")]
public sealed class SqliteApiKeyStoreImporterLiveTests : IAsyncLifetime
{
private readonly string _schema = LiveSqlServer.NewSchemaName();
private readonly string _sqlitePath =
Path.Combine(Path.GetTempPath(), $"zbauth-import-{Guid.NewGuid():N}.db");
private AuthSqlServerConnectionFactory _factory = null!;
private SqlServerApiKeyAdminStore _sqlAdmin = null!;
private SqlServerApiKeyStore _sqlRead = null!;
private SqlServerApiKeyAuditStore _sqlAudit = null!;
private SqliteApiKeyStoreImporter _importer = null!;
/// <inheritdoc />
public async Task InitializeAsync()
{
if (!LiveSqlServer.IsEnabled)
{
return;
}
_factory = new AuthSqlServerConnectionFactory(LiveSqlServer.OptionsFor(_schema));
await new SqlServerApiKeyStoreMigrator(_factory).MigrateAsync(CancellationToken.None);
_sqlAdmin = new SqlServerApiKeyAdminStore(_factory);
_sqlRead = new SqlServerApiKeyStore(_factory);
_sqlAudit = new SqlServerApiKeyAuditStore(_factory);
_importer = new SqliteApiKeyStoreImporter(_factory);
}
/// <inheritdoc />
public async Task DisposeAsync()
{
// SQLite pools connections by connection string; the handle must be released before the
// file can be removed cleanly.
SqliteConnection.ClearAllPools();
foreach (string path in new[] { _sqlitePath, _sqlitePath + "-wal", _sqlitePath + "-shm" })
{
if (File.Exists(path))
{
File.Delete(path);
}
}
await LiveSqlServer.DropSchemaAsync(_schema);
}
[SkippableFact]
public async Task Import_CopiesKeysAndAuditRows_AndReturnsCounts()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
(ApiKeyRecord keyA, ApiKeyRecord keyB) = await SeedSqliteAsync();
ApiKeyImportResult result = await _importer.ImportAsync(_sqlitePath, CancellationToken.None);
Assert.True(result.SourceFound);
Assert.Equal(2, result.KeysInserted);
Assert.Equal(0, result.KeysSkipped);
Assert.Equal(3, result.AuditInserted);
Assert.Equal(0, result.AuditSkipped);
await AssertRecordMatchesAsync(keyA);
await AssertRecordMatchesAsync(keyB);
IReadOnlyList<ApiKeyAuditEntry> audit = await _sqlAudit.ListRecentAsync(10, CancellationToken.None);
Assert.Equal(3, audit.Count);
Assert.Contains(audit, e => e.KeyId is null && e.EventType == "auth_failed");
Assert.Contains(audit, e => e.KeyId == "key-a" && e.EventType == "created");
Assert.Contains(audit, e => e.KeyId == "key-b" && e.EventType == "created");
}
[SkippableFact]
public async Task Import_Twice_IsIdempotent()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await SeedSqliteAsync();
await _importer.ImportAsync(_sqlitePath, CancellationToken.None);
ApiKeyImportResult second = await _importer.ImportAsync(_sqlitePath, CancellationToken.None);
Assert.True(second.SourceFound);
Assert.Equal(0, second.KeysInserted);
Assert.Equal(2, second.KeysSkipped);
Assert.Equal(0, second.AuditInserted);
Assert.Equal(3, second.AuditSkipped);
Assert.Equal(2, (await _sqlAdmin.ListAsync(CancellationToken.None)).Count);
Assert.Equal(3, (await _sqlAudit.ListRecentAsync(10, CancellationToken.None)).Count);
}
[SkippableFact]
public async Task Import_UnionsWithExistingRows()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
var lastUsed = new DateTimeOffset(2026, 7, 4, 12, 0, 0, TimeSpan.Zero);
ApiKeyRecord keyC = SampleRecord("key-c") with { LastUsedUtc = lastUsed };
await _sqlAdmin.CreateAsync(keyC, CancellationToken.None);
await SeedSqliteAsync();
ApiKeyImportResult result = await _importer.ImportAsync(_sqlitePath, CancellationToken.None);
Assert.Equal(2, result.KeysInserted);
Assert.Equal(0, result.KeysSkipped);
IReadOnlyList<ApiKeyListItem> listed = await _sqlAdmin.ListAsync(CancellationToken.None);
Assert.Equal(
["key-a", "key-b", "key-c"],
listed.Select(k => k.KeyId).OrderBy(k => k, StringComparer.Ordinal));
// The pre-existing row is untouched — the importer only ever inserts.
Assert.Equal(lastUsed, Assert.Single(listed, k => k.KeyId == "key-c").LastUsedUtc);
}
[SkippableFact]
public async Task Import_MissingFile_ReturnsZeroWithoutThrowing()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
ApiKeyImportResult result = await _importer.ImportAsync(
Path.Combine(Path.GetTempPath(), $"zbauth-absent-{Guid.NewGuid():N}.db"),
CancellationToken.None);
Assert.False(result.SourceFound);
Assert.Equal(0, result.KeysInserted);
Assert.Equal(0, result.KeysSkipped);
Assert.Equal(0, result.AuditInserted);
Assert.Equal(0, result.AuditSkipped);
}
[SkippableFact]
public async Task Import_PreV3FileWithoutExpiresColumn_ReadsExpiryAsNull()
{
Skip.IfNot(LiveSqlServer.IsEnabled, LiveSqlServer.SkipReason);
await CreatePreV3SqliteFileAsync();
ApiKeyImportResult result = await _importer.ImportAsync(_sqlitePath, CancellationToken.None);
Assert.True(result.SourceFound);
Assert.Equal(1, result.KeysInserted);
ApiKeyRecord? found = await _sqlRead.FindByKeyIdAsync("key-old", CancellationToken.None);
Assert.NotNull(found);
Assert.Null(found!.ExpiresUtc);
Assert.Equal("legacy key", found.DisplayName);
Assert.Equal(new DateTimeOffset(2026, 1, 2, 3, 4, 5, TimeSpan.Zero), found.CreatedUtc);
}
// --- helpers ---
/// <summary>
/// Seeds the throwaway SQLite file with two keys (one revoked, one with an expiry) and three
/// audit rows (one of them key-less), then returns the two key records as SQLite holds them.
/// </summary>
private async Task<(ApiKeyRecord KeyA, ApiKeyRecord KeyB)> SeedSqliteAsync()
{
var sqliteFactory = new AuthSqliteConnectionFactory(_sqlitePath);
await new SqliteAuthStoreMigrator(sqliteFactory).MigrateAsync(CancellationToken.None);
var admin = new SqliteApiKeyAdminStore(sqliteFactory);
var audit = new SqliteApiKeyAuditStore(sqliteFactory);
var read = new SqliteApiKeyStore(sqliteFactory);
ApiKeyRecord keyA = SampleRecord("key-a");
ApiKeyRecord keyB = SampleRecord("key-b") with
{
ExpiresUtc = new DateTimeOffset(2027, 3, 1, 0, 0, 0, TimeSpan.Zero),
};
await admin.CreateAsync(keyA, CancellationToken.None);
await admin.CreateAsync(keyB, CancellationToken.None);
await admin.RevokeAsync("key-a", new DateTimeOffset(2026, 6, 1, 7, 8, 9, TimeSpan.Zero), CancellationToken.None);
await audit.AppendAsync(
new ApiKeyAuditEntry("key-a", "created", "10.0.0.1", new DateTimeOffset(2026, 5, 1, 8, 30, 0, TimeSpan.Zero), "by admin"),
CancellationToken.None);
await audit.AppendAsync(
new ApiKeyAuditEntry("key-b", "created", null, new DateTimeOffset(2026, 5, 1, 8, 31, 0, TimeSpan.Zero), null),
CancellationToken.None);
await audit.AppendAsync(
new ApiKeyAuditEntry(null, "auth_failed", "10.0.0.9", new DateTimeOffset(2026, 5, 2, 9, 0, 0, TimeSpan.Zero), "unknown key"),
CancellationToken.None);
// Re-read so the assertions compare against exactly what SQLite holds, revocation included.
ApiKeyRecord storedA = (await read.FindByKeyIdAsync("key-a", CancellationToken.None))!;
ApiKeyRecord storedB = (await read.FindByKeyIdAsync("key-b", CancellationToken.None))!;
return (storedA, storedB);
}
/// <summary>
/// Writes a v2-shaped SQLite file by hand — <c>api_keys</c> WITHOUT <c>expires_utc</c> — and
/// inserts one key row, reproducing a store created before schema v3.
/// </summary>
private async Task CreatePreV3SqliteFileAsync()
{
await using var connection = new SqliteConnection(
new SqliteConnectionStringBuilder { DataSource = _sqlitePath }.ToString());
await connection.OpenAsync();
await using SqliteCommand ddl = connection.CreateCommand();
ddl.CommandText = """
CREATE TABLE api_keys (
key_id TEXT PRIMARY KEY,
key_prefix TEXT NOT NULL,
secret_hash BLOB NOT NULL,
display_name TEXT NOT NULL,
scopes TEXT NOT NULL,
constraints TEXT NULL,
created_utc TEXT NOT NULL,
last_used_utc TEXT NULL,
revoked_utc TEXT NULL
);
CREATE TABLE api_key_audit (
audit_id INTEGER PRIMARY KEY AUTOINCREMENT,
key_id TEXT NULL,
event_type TEXT NOT NULL,
remote_address TEXT NULL,
created_utc TEXT NOT NULL,
details TEXT NULL
);
""";
await ddl.ExecuteNonQueryAsync();
await using SqliteCommand insert = connection.CreateCommand();
insert.CommandText = """
INSERT INTO api_keys (
key_id, key_prefix, secret_hash, display_name, scopes,
constraints, created_utc, last_used_utc, revoked_utc)
VALUES ('key-old', 'sbk_old1', $hash, 'legacy key', 'read', NULL, $created, NULL, NULL);
""";
insert.Parameters.Add("$hash", SqliteType.Blob).Value = new byte[] { 4, 5, 6 };
insert.Parameters.AddWithValue(
"$created", new DateTimeOffset(2026, 1, 2, 3, 4, 5, TimeSpan.Zero).ToString("O"));
await insert.ExecuteNonQueryAsync();
}
private async Task AssertRecordMatchesAsync(ApiKeyRecord expected)
{
ApiKeyRecord? actual = await _sqlRead.FindByKeyIdAsync(expected.KeyId, CancellationToken.None);
Assert.NotNull(actual);
Assert.Equal(expected.KeyPrefix, actual!.KeyPrefix);
Assert.True(expected.SecretHash.SequenceEqual(actual.SecretHash));
Assert.Equal(expected.DisplayName, actual.DisplayName);
Assert.True(expected.Scopes.SetEquals(actual.Scopes));
Assert.Equal(expected.ConstraintsJson, actual.ConstraintsJson);
Assert.Equal(expected.CreatedUtc, actual.CreatedUtc);
Assert.Equal(expected.LastUsedUtc, actual.LastUsedUtc);
Assert.Equal(expected.RevokedUtc, actual.RevokedUtc);
Assert.Equal(expected.ExpiresUtc, actual.ExpiresUtc);
}
private static ApiKeyRecord SampleRecord(string keyId) => new(
KeyId: keyId,
KeyPrefix: "sbk_ab12",
SecretHash: [1, 2, 3, 4, 5, 6, 7, 8],
DisplayName: "Test Key " + keyId,
Scopes: new HashSet<string>(["read", "write"], StringComparer.Ordinal),
ConstraintsJson: """{"ipAllow":["10.0.0.0/8"]}""",
CreatedUtc: new DateTimeOffset(2026, 5, 1, 8, 30, 0, TimeSpan.Zero),
LastUsedUtc: null,
RevokedUtc: null);
}
@@ -0,0 +1,16 @@
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests;
public sealed class SqlServerApiKeyOptionsTests
{
[Fact]
public void Validate_RejectsMissingConnectionString() =>
Assert.Throws<InvalidOperationException>(() => new SqlServerApiKeyOptions { ConnectionString = " " }.Validate());
[Fact]
public void Validate_RejectsUnsafeSchemaName() =>
Assert.Throws<InvalidOperationException>(() => new SqlServerApiKeyOptions { ConnectionString = "Server=x", Schema = "zb;auth" }.Validate());
[Fact]
public void Schema_DefaultsToZbauth() =>
Assert.Equal("zbauth", new SqlServerApiKeyOptions().Schema);
}
@@ -0,0 +1,66 @@
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
using ZB.MOM.WW.Auth.ApiKeys.SqlServer.DependencyInjection;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests;
public sealed class SqlServerApiKeyServiceCollectionExtensionsTests
{
private static IConfiguration MinimalConfig() =>
new ConfigurationBuilder().AddInMemoryCollection(new Dictionary<string, string?>
{
["ApiKeys:TokenPrefix"] = "sbk",
["ApiKeys:PepperSecretName"] = "Pepper",
["Pepper"] = "0123456789abcdef",
["ApiKeys:SqlServer:ConnectionString"] = "Server=unused;TrustServerCertificate=true",
}).Build();
[Fact]
public void AddZbApiKeyAuthSqlServer_DisplacesSqliteStoresAndMigrator()
{
var services = new ServiceCollection();
services.AddZbApiKeyAuthSqlServer(MinimalConfig(), "ApiKeys", "ApiKeys:SqlServer");
using ServiceProvider sp = services.BuildServiceProvider();
Assert.IsType<SqlServerApiKeyStore>(sp.GetRequiredService<IApiKeyStore>());
Assert.IsType<SqlServerApiKeyAdminStore>(sp.GetRequiredService<IApiKeyAdminStore>());
Assert.IsType<SqlServerApiKeyAuditStore>(sp.GetRequiredService<IApiKeyAuditStore>());
Assert.IsType<SqlServerApiKeyStoreMigrator>(sp.GetRequiredService<IApiKeyStoreMigrator>());
Assert.NotNull(sp.GetRequiredService<SqliteApiKeyStoreImporter>());
Assert.NotNull(sp.GetRequiredService<IApiKeyVerifier>());
}
[Fact]
public void AddZbApiKeyAuthSqlServer_BindsSqlServerOptionsFromSection()
{
var config = new ConfigurationBuilder().AddInMemoryCollection(new Dictionary<string, string?>
{
["ApiKeys:TokenPrefix"] = "sbk",
["ApiKeys:PepperSecretName"] = "Pepper",
["Pepper"] = "0123456789abcdef",
["ApiKeys:SqlServer:ConnectionString"] = "Server=my-shared-sql;TrustServerCertificate=true",
["ApiKeys:SqlServer:Schema"] = "zbauth_custom",
}).Build();
var services = new ServiceCollection();
services.AddZbApiKeyAuthSqlServer(config, "ApiKeys", "ApiKeys:SqlServer");
using ServiceProvider sp = services.BuildServiceProvider();
SqlServerApiKeyOptions options = sp.GetRequiredService<IOptions<SqlServerApiKeyOptions>>().Value;
Assert.Equal("Server=my-shared-sql;TrustServerCertificate=true", options.ConnectionString);
Assert.Equal("zbauth_custom", options.Schema);
}
[Fact]
public void AddZbApiKeyAuthSqlServer_RegistersMigrationHostedService()
{
var services = new ServiceCollection();
services.AddZbApiKeyAuthSqlServer(MinimalConfig(), "ApiKeys", "ApiKeys:SqlServer");
using ServiceProvider sp = services.BuildServiceProvider();
IEnumerable<IHostedService> hostedServices = sp.GetServices<IHostedService>();
Assert.Contains(hostedServices, s => s.GetType().Name == "ApiKeyMigrationHostedService");
}
}
@@ -0,0 +1,43 @@
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests;
/// <summary>
/// Offline pins for the migrator's retry classification. A <see cref="Microsoft.Data.SqlClient.SqlException"/>
/// cannot be constructed normally, so the error-number predicate is extracted as an internal static
/// and pinned here by number; the concurrent-provision behaviour itself is exercised by the
/// env-gated live suite. These run on any machine, so the retry filter stays pinned even when the
/// live suite skips.
/// </summary>
public sealed class SqlServerApiKeyStoreMigratorTests
{
/// <summary>
/// The provisioning-race outcomes the ScadaBridge central shared-store live gate (2026-08-07)
/// proved reachable — or that the multi-statement DDL makes reachable — when N nodes provision
/// one virgin database at once. Losing such a race means the object now exists, which is the
/// desired end state, so a retry of the idempotent IF NOT EXISTS path must be taken.
/// </summary>
/// <param name="errorNumber">The SQL Server error number under test.</param>
[Theory]
[InlineData(1205)] // deadlock victim
[InlineData(2714)] // "There is already an object named ..." — lost CREATE SCHEMA/TABLE (the live-gate defect)
[InlineData(1913)] // "index ... already exists" — lost CREATE INDEX
[InlineData(2627)] // PK violation — lost schema_version MERGE-insert
public void Provisioning_race_error_numbers_are_retryable(int errorNumber)
=> Assert.True(SqlServerApiKeyStoreMigrator.IsRetryableMigrationErrorNumber(errorNumber));
/// <summary>
/// Errors that reproduce identically on retry must propagate so the node fails closed instead
/// of spinning through the retry budget against a genuine misconfiguration.
/// </summary>
/// <param name="errorNumber">The SQL Server error number under test.</param>
[Theory]
[InlineData(2705)] // duplicate column — unreachable from the race (single CREATE TABLE statement)
[InlineData(208)] // invalid object name
[InlineData(229)] // permission denied
[InlineData(2759)] // "CREATE SCHEMA failed due to previous errors" — retryable only via its companion 2714
[InlineData(4060)] // cannot open database
[InlineData(18456)] // login failed
[InlineData(0)]
[InlineData(-2)] // client-side timeout
public void Non_race_error_numbers_are_not_retryable(int errorNumber)
=> Assert.False(SqlServerApiKeyStoreMigrator.IsRetryableMigrationErrorNumber(errorNumber));
}
@@ -0,0 +1,77 @@
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests;
/// <summary>
/// Auth-008 (scadaproj#46), the offline half: a value longer than its column is rejected or treated
/// as absent BEFORE any connection is opened. Every <c>SqlParameter</c> carries an explicit size, and
/// SqlClient truncates an over-length value to that size silently — so a 70-character key id was
/// stored as its first 64 characters, and a different 70-character id sharing that prefix then
/// "found" it. These tests point at a refused loopback port: pre-fix they reach the network and throw
/// <c>SqlException</c>; post-fix nothing is sent.
/// </summary>
public sealed class SqlServerColumnLimitTests
{
private static readonly AuthSqlServerConnectionFactory Unreachable = new(new SqlServerApiKeyOptions
{
ConnectionString = "Server=tcp:127.0.0.1,1;Connect Timeout=3;ConnectRetryCount=0;TrustServerCertificate=true",
});
private static readonly string LongKeyId = new('k', 65);
private static ApiKeyRecord Record(string keyId = "key-1", string prefix = "sbk", string displayName = "Key") => new(
KeyId: keyId,
KeyPrefix: prefix,
SecretHash: [1, 2, 3],
DisplayName: displayName,
Scopes: new HashSet<string>(StringComparer.Ordinal),
ConstraintsJson: null,
CreatedUtc: DateTimeOffset.UnixEpoch,
LastUsedUtc: null,
RevokedUtc: null);
public static TheoryData<ApiKeyRecord, string> OverLength() => new()
{
{ Record(keyId: LongKeyId), "KeyId" },
{ Record(prefix: new string('p', 17)), "KeyPrefix" },
{ Record(displayName: new string('d', 257)), "DisplayName" },
};
[Theory]
[MemberData(nameof(OverLength))]
public async Task Create_OverLengthValue_IsRejected_NotTruncated(ApiKeyRecord record, string field)
{
var store = new SqlServerApiKeyAdminStore(Unreachable);
var ex = await Assert.ThrowsAsync<ArgumentException>(() => store.CreateAsync(record, CancellationToken.None));
Assert.Contains(field, ex.Message, StringComparison.Ordinal);
}
[Fact]
public async Task Create_AtTheColumnLimits_ReachesTheDatabase()
{
// Positive control: values exactly at the limits are not rejected — the call gets as far as
// the (unreachable) server.
var store = new SqlServerApiKeyAdminStore(Unreachable);
var record = Record(keyId: new string('k', 64), prefix: new string('p', 16), displayName: new string('d', 256));
await Assert.ThrowsAsync<Microsoft.Data.SqlClient.SqlException>(() => store.CreateAsync(record, CancellationToken.None));
}
[Fact]
public async Task Lookups_OfAnOverLengthKeyId_FindNothing_WithoutQuerying()
{
var read = new SqlServerApiKeyStore(Unreachable);
var admin = new SqlServerApiKeyAdminStore(Unreachable);
var now = DateTimeOffset.UnixEpoch;
Assert.Null(await read.FindByKeyIdAsync(LongKeyId, CancellationToken.None));
Assert.Null(await read.FindActiveByKeyIdAsync(LongKeyId, CancellationToken.None));
await read.MarkUsedAsync(LongKeyId, now, CancellationToken.None);
Assert.False(await admin.RevokeAsync(LongKeyId, now, CancellationToken.None));
Assert.False(await admin.RotateAsync(LongKeyId, [1], CancellationToken.None));
Assert.False(await admin.SetScopesAsync(LongKeyId, new HashSet<string>(), CancellationToken.None));
Assert.False(await admin.SetEnabledAsync(LongKeyId, true, now, CancellationToken.None));
Assert.False(await admin.DeleteAsync(LongKeyId, CancellationToken.None));
}
}
@@ -0,0 +1,34 @@
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
namespace ZB.MOM.WW.Auth.ApiKeys.SqlServer.Tests;
/// <summary>
/// Auth-010 (scadaproj#46), end to end through the real SQL Server store with no server: the shared
/// store being unreachable (failover, lost route) must come back from <c>VerifyAsync</c> as a
/// structured <see cref="ApiKeyFailure.StoreUnavailable"/>, not as a <c>SqlException</c> that
/// surfaces as an unaudited 500. Offline: it dials a refused local port.
/// </summary>
public sealed class SqlServerUnreachableVerifierTests
{
private sealed class Pepper : IApiKeyPepperProvider
{
public string? GetPepper() => "0123456789abcdef";
}
[Fact]
public async Task VerifyAsync_AgainstAnUnreachableSqlServer_ReturnsStoreUnavailable()
{
var factory = new AuthSqlServerConnectionFactory(new SqlServerApiKeyOptions
{
// Port 1 on loopback refuses immediately; no retries, so the test stays fast.
ConnectionString = "Server=tcp:127.0.0.1,1;Connect Timeout=3;ConnectRetryCount=0;TrustServerCertificate=true",
});
var verifier = new ApiKeyVerifier(
new ApiKeyOptions { TokenPrefix = "sbk" }, new SqlServerApiKeyStore(factory), new Pepper());
var result = await verifier.VerifyAsync("sbk_line1_supersecretvalue", CancellationToken.None);
Assert.False(result.Succeeded);
Assert.Equal(ApiKeyFailure.StoreUnavailable, result.Failure);
}
}
@@ -0,0 +1,30 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<IsPackable>false</IsPackable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="coverlet.collector" />
<PackageReference Include="Microsoft.NET.Test.Sdk" />
<PackageReference Include="xunit" />
<PackageReference Include="xunit.runner.visualstudio" />
<!-- Live tests (Task 3+) skip rather than fail when AUTH_SQLSERVER_CONNSTR is unset. -->
<PackageReference Include="Xunit.SkippableFact" />
<PackageReference Include="Microsoft.Extensions.DependencyInjection" />
<PackageReference Include="Microsoft.Extensions.Configuration" />
<PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" />
<PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" />
</ItemGroup>
<ItemGroup>
<Using Include="Xunit" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\..\src\ZB.MOM.WW.Auth.ApiKeys.SqlServer\ZB.MOM.WW.Auth.ApiKeys.SqlServer.csproj" />
<ProjectReference Include="..\..\src\ZB.MOM.WW.Auth.ApiKeys\ZB.MOM.WW.Auth.ApiKeys.csproj" />
<ProjectReference Include="..\..\src\ZB.MOM.WW.Auth.Abstractions\ZB.MOM.WW.Auth.Abstractions.csproj" />
</ItemGroup>
</Project>
@@ -163,7 +163,7 @@ public sealed class ApiKeyAdminCommandsTests : IAsyncLifetime
int auditCountBefore = (await _audit.ListRecentAsync(50, CancellationToken.None)).Count;
await Assert.ThrowsAsync<InvalidOperationException>(() => commands.CreateKeyAsync(
await Assert.ThrowsAsync<ApiKeyPepperUnavailableException>(() => commands.CreateKeyAsync(
"key-x",
"No Pepper",
new HashSet<string>(StringComparer.Ordinal),
@@ -297,6 +297,52 @@ public sealed class ApiKeyAdminCommandsTests : IAsyncLifetime
Assert.Equal("not-found", auditRow.Details);
}
[Fact]
public async Task PepperUnavailable_IsStillCatchableAsInvalidOperationException_WithOriginalMessage()
{
// Back-compat: consumers that caught InvalidOperationException before the typed exception
// existed must keep working, for both create and rotate.
ApiKeyAdminCommands setup = BuildCommands(pepper: Pepper);
await setup.InitDbAsync(null, CancellationToken.None);
await setup.CreateKeyAsync("key-bc", "BC", new HashSet<string>(StringComparer.Ordinal), null, null, CancellationToken.None);
ApiKeyAdminCommands nopepper = BuildCommands(pepper: null);
InvalidOperationException create = await Assert.ThrowsAnyAsync<InvalidOperationException>(() =>
nopepper.CreateKeyAsync("key-bc2", "BC2", new HashSet<string>(StringComparer.Ordinal), null, null, CancellationToken.None));
InvalidOperationException rotate = await Assert.ThrowsAnyAsync<InvalidOperationException>(() =>
nopepper.RotateKeyAsync("key-bc", null, CancellationToken.None));
Assert.IsType<ApiKeyPepperUnavailableException>(create);
Assert.IsType<ApiKeyPepperUnavailableException>(rotate);
Assert.Equal("pepper unavailable", create.Message);
Assert.Equal("pepper unavailable", rotate.Message);
}
[Theory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public async Task CreateKey_NullEmptyOrWhitespacePepper_ThrowsTypedException(string? pepper)
{
ApiKeyAdminCommands commands = BuildCommands(pepper);
await new ApiKeyAdminCommands(_options, _admin, _audit, new FakePepperProvider(Pepper), _migrator)
.InitDbAsync(null, CancellationToken.None);
await Assert.ThrowsAsync<ApiKeyPepperUnavailableException>(() => commands.CreateKeyAsync(
"key-w", "W", new HashSet<string>(StringComparer.Ordinal), null, null, CancellationToken.None));
}
[Fact]
public void PepperUnavailableException_ConstructorOverloads_AreInvalidOperationExceptions()
{
var inner = new Exception("inner");
Assert.Equal("pepper unavailable", new ApiKeyPepperUnavailableException().Message);
Assert.Equal("custom", new ApiKeyPepperUnavailableException("custom").Message);
var withInner = new ApiKeyPepperUnavailableException("m", inner);
Assert.Same(inner, withInner.InnerException);
Assert.IsAssignableFrom<InvalidOperationException>(withInner);
}
[Fact]
public async Task RotateKey_PepperUnavailable_Throws_HashUnchanged_AndAppendsNoAudit()
{
@@ -319,7 +365,7 @@ public sealed class ApiKeyAdminCommandsTests : IAsyncLifetime
// Act: rotate with no pepper available.
ApiKeyAdminCommands nopepper = BuildCommands(pepper: null);
await Assert.ThrowsAsync<InvalidOperationException>(() =>
await Assert.ThrowsAsync<ApiKeyPepperUnavailableException>(() =>
nopepper.RotateKeyAsync("key-1", null, CancellationToken.None));
// Assert: stored hash is unchanged.
@@ -5,6 +5,7 @@ using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;
using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
using ZB.MOM.WW.Auth.ApiKeys.DependencyInjection;
using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
namespace ZB.MOM.WW.Auth.ApiKeys.Tests;
@@ -197,4 +198,37 @@ public class ApiKeyServiceCollectionExtensionsTests
File.Delete(sqlitePath);
}
}
[Fact]
public void AddZbApiKeyAuth_RegistersSqliteMigratorAsIApiKeyStoreMigrator()
{
IConfiguration config = BuildConfiguration(TempSqlitePath());
var services = new ServiceCollection();
services.AddZbApiKeyAuth(config, ApiKeySection);
using ServiceProvider sp = services.BuildServiceProvider();
Assert.IsType<SqliteAuthStoreMigrator>(sp.GetRequiredService<IApiKeyStoreMigrator>());
Assert.Same(sp.GetRequiredService<SqliteAuthStoreMigrator>(), sp.GetRequiredService<IApiKeyStoreMigrator>());
}
[Fact]
public void AddZbApiKeyAuth_LeavesPreRegisteredMigratorInPlace()
{
var services = new ServiceCollection();
var fake = new FakeMigrator();
services.AddSingleton<IApiKeyStoreMigrator>(fake);
services.AddZbApiKeyAuth(BuildConfiguration(TempSqlitePath()), ApiKeySection);
using ServiceProvider sp = services.BuildServiceProvider();
Assert.Same(fake, sp.GetRequiredService<IApiKeyStoreMigrator>());
}
private sealed class FakeMigrator : IApiKeyStoreMigrator
{
public Task MigrateAsync(CancellationToken ct) => Task.CompletedTask;
}
}
@@ -356,6 +356,45 @@ public class ApiKeyVerifierTests
// --- Cancellation ---
// --- StoreUnavailable (Auth-010, scadaproj#46) ---
public static TheoryData<Exception> StoreFaults() => new()
{
// Stand-ins for what real stores throw: a database fault (SqlClient's SqlException on a
// closed port or failover), an InvalidOperationException (e.g. a pooled connection in a bad
// state), and an I/O fault from a local SQLite file.
new System.Data.DataException("store unreachable"),
new InvalidOperationException("The connection is in a broken state."),
new IOException("disk I/O error"),
};
[Theory]
[MemberData(nameof(StoreFaults))]
public async Task VerifyAsync_StoreLookupThrows_ReturnsStoreUnavailable_InsteadOfThrowing(Exception fault)
{
var store = new FakeApiKeyStore { FindException = fault };
var verifier = BuildVerifier(store, new FakePepperProvider(Pepper));
ApiKeyVerification result = await verifier.VerifyAsync(Header(KeyId, Secret), CancellationToken.None);
Assert.False(result.Succeeded);
Assert.Equal(ApiKeyFailure.StoreUnavailable, result.Failure);
Assert.Null(result.Identity);
Assert.True(store.FindByKeyIdCalled);
Assert.False(store.MarkUsedCalled);
}
[Fact]
public async Task VerifyAsync_StoreLookupCancelled_Propagates()
{
// Cancellation stays the one exception path.
var store = new FakeApiKeyStore { FindException = new OperationCanceledException() };
var verifier = BuildVerifier(store, new FakePepperProvider(Pepper));
await Assert.ThrowsAnyAsync<OperationCanceledException>(
() => verifier.VerifyAsync(Header(KeyId, Secret), CancellationToken.None));
}
[Fact]
public async Task VerifyAsync_AlreadyCancelled_Throws()
{
@@ -398,10 +437,13 @@ public class ApiKeyVerifierTests
/// <summary>When set, <see cref="MarkUsedAsync"/> throws this exception (after recording the call).</summary>
public Exception? MarkUsedException { get; set; }
/// <summary>When set, <see cref="FindByKeyIdAsync"/> throws this exception (after recording the call).</summary>
public Exception? FindException { get; set; }
public Task<ApiKeyRecord?> FindByKeyIdAsync(string keyId, CancellationToken ct)
{
FindByKeyIdCalled = true;
return Task.FromResult(Record);
return FindException is not null ? Task.FromException<ApiKeyRecord?>(FindException) : Task.FromResult(Record);
}
public Task<ApiKeyRecord?> FindActiveByKeyIdAsync(string keyId, CancellationToken ct) =>
@@ -134,4 +134,74 @@ public class ServiceCollectionExtensionsTests
await host.StartAsync();
await host.StopAsync();
}
[Fact]
public void AddZbLdapAuth_BindsUserBindModeKeys()
{
IConfiguration config = new ConfigurationBuilder()
.AddInMemoryCollection(new Dictionary<string, string?>
{
[$"{LdapSection}:Server"] = LdapServer,
[$"{LdapSection}:SearchBase"] = "dc=example,dc=com",
[$"{LdapSection}:Transport"] = nameof(LdapTransport.Ldaps),
[$"{LdapSection}:BindMode"] = "User",
[$"{LdapSection}:UserBindTemplate"] = "{0}@corp.test",
[$"{LdapSection}:AcceptDomainQualifiedNames"] = "false",
})
.Build();
var services = new ServiceCollection();
services.AddZbLdapAuth(config, LdapSection);
using ServiceProvider provider = services.BuildServiceProvider();
var options = provider.GetRequiredService<IOptions<LdapOptions>>().Value;
Assert.Equal(LdapBindMode.User, options.BindMode);
Assert.Equal("{0}@corp.test", options.UserBindTemplate);
Assert.False(options.AcceptDomainQualifiedNames);
}
}
public class LdapGroupLookupRegistrationTests
{
private static IConfiguration Config() =>
new ConfigurationBuilder()
.AddInMemoryCollection(new Dictionary<string, string?>
{
["Auth:Ldap:Server"] = "ldap.example.com",
["Auth:Ldap:SearchBase"] = "dc=example,dc=com",
["Auth:Ldap:ServiceAccountDn"] = "cn=svc,dc=example,dc=com",
})
.Build();
[Fact]
public void AddZbLdapAuth_ResolvesGroupLookup_AsTheSameInstanceAsTheAuthService()
{
var services = new ServiceCollection().AddZbLdapAuth(Config(), "Auth:Ldap");
using var provider = services.BuildServiceProvider();
var lookup = provider.GetRequiredService<ILdapGroupLookup>();
Assert.IsType<LdapAuthService>(lookup);
Assert.Same(provider.GetRequiredService<ILdapAuthService>(), lookup);
}
[Fact]
public async Task AddZbLdapAuth_WithAForeignAuthService_ResolvesANotSupportedLookup()
{
var services = new ServiceCollection();
services.AddSingleton<ILdapAuthService, StubAuth>();
services.AddZbLdapAuth(Config(), "Auth:Ldap");
using var provider = services.BuildServiceProvider();
var result = await provider.GetRequiredService<ILdapGroupLookup>().GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.NotSupported, result.Status);
}
private sealed class StubAuth : ILdapAuthService
{
public Task<LdapAuthResult> AuthenticateAsync(string username, string password, CancellationToken ct)
=> Task.FromResult(LdapAuthResult.Fail(LdapAuthFailure.Disabled));
}
}
@@ -16,6 +16,12 @@ internal sealed class FakeLdapConnection : ILdapConnection
private bool _throwOnConnect;
private bool _throwOnServiceBind;
private bool _throwOnUserBind;
private int? _firstBindResultCode;
private bool _throwOnSearch;
private string? _whoAmI;
private string? _principalName;
private bool _throwOnRead;
private readonly Dictionary<string, List<LdapSearchEntry>> _filterResults = new(StringComparer.Ordinal);
// ---- observation -----
@@ -32,13 +38,24 @@ internal sealed class FakeLdapConnection : ILdapConnection
/// </summary>
public int BindAttempts { get; private set; }
/// <summary>The attribute list passed to the most recent <see cref="Search"/> call (the fake still returns every scripted attribute).</summary>
public IReadOnlyList<string>? SearchAttributes { get; private set; }
/// <summary>Every call in order: <c>connect</c>, <c>bind:&lt;dn&gt;</c>, <c>search:&lt;filter&gt;</c>.</summary>
public List<string> Calls { get; } = new();
// ---- builder methods -----
/// <summary>
/// Scripts a user entry that will be returned by the next <see cref="Search"/> call.
/// Builds a minimal attribute bag with <c>memberOf</c> and optional <c>displayName</c>.
/// Builds a minimal attribute bag with <c>memberOf</c>, optional <c>displayName</c> and any
/// <paramref name="extraAttributes"/> (e.g. <c>sAMAccountName</c>) the test needs.
/// </summary>
public FakeLdapConnection WithUserEntry(string dn, string[] memberOf, string? displayName = null)
public FakeLdapConnection WithUserEntry(
string dn,
string[] memberOf,
string? displayName = null,
IReadOnlyDictionary<string, string[]>? extraAttributes = null)
{
var attrs = new Dictionary<string, IReadOnlyList<string>>(StringComparer.OrdinalIgnoreCase)
{
@@ -46,6 +63,11 @@ internal sealed class FakeLdapConnection : ILdapConnection
};
if (displayName is not null)
attrs["displayName"] = new[] { displayName };
if (extraAttributes is not null)
{
foreach (var (name, values) in extraAttributes)
attrs[name] = values;
}
_scriptedEntries.Add(new LdapSearchEntry(dn, attrs));
return this;
@@ -83,6 +105,67 @@ internal sealed class FakeLdapConnection : ILdapConnection
return this;
}
/// <summary>
/// Throw <see cref="Novell.Directory.Ldap.LdapException"/> with <paramref name="resultCode"/> on the
/// FIRST bind. In user-bind mode the first bind is the user's own, so 49 simulates a wrong
/// password and e.g. 52 (Unavailable) a domain controller that cannot answer.
/// </summary>
public FakeLdapConnection ThrowOnFirstBind(int resultCode)
{
_firstBindResultCode = resultCode;
return this;
}
/// <summary>
/// Scripts the RFC 4532 Who-am-I answer (e.g. <c>dn:CN=Jane,DC=x</c> or <c>u:CORP\jane</c>).
/// Unscripted, <see cref="WhoAmI"/> throws protocol error 2 — what GLAuth answers.
/// </summary>
public FakeLdapConnection WithWhoAmI(string authzId)
{
_whoAmI = authzId;
return this;
}
/// <summary>
/// Scripts AD's constructed <c>msDS-PrincipalName</c> (<c>DOMAIN\name</c>) that a base
/// <see cref="Read"/> of any DN returns. Unscripted, <see cref="Read"/> returns the entry without it.
/// </summary>
public FakeLdapConnection WithPrincipalName(string value)
{
_principalName = value;
return this;
}
/// <summary>Throw <see cref="Novell.Directory.Ldap.LdapException"/> from <see cref="Read"/>.</summary>
public FakeLdapConnection ThrowOnRead()
{
_throwOnRead = true;
return this;
}
/// <summary>
/// Scripts the entries a <see cref="Search"/> with exactly <paramref name="filter"/> returns, each
/// carrying the given <c>sAMAccountName</c>. Other filters still return the
/// <see cref="WithUserEntry"/> entries.
/// </summary>
public FakeLdapConnection WithSearchResult(string filter, params (string Dn, string Sam)[] entries)
{
_filterResults[filter] = entries
.Select(e => new LdapSearchEntry(e.Dn, new Dictionary<string, IReadOnlyList<string>>(StringComparer.OrdinalIgnoreCase)
{
["sAMAccountName"] = new[] { e.Sam },
}))
.ToList();
return this;
}
/// <summary>Throw <see cref="Novell.Directory.Ldap.LdapException"/> from <see cref="Search"/> (unhealthy directory).</summary>
public FakeLdapConnection ThrowOnSearch()
{
_throwOnSearch = true;
return this;
}
/// <summary>
/// Throw <see cref="Novell.Directory.Ldap.LdapException"/> from <see cref="Connect"/> to
/// simulate an unreachable directory (infrastructure failure).
@@ -120,6 +203,7 @@ internal sealed class FakeLdapConnection : ILdapConnection
int timeoutMs,
RemoteCertificateValidationCallback? serverCertificateValidationCallback = null)
{
Calls.Add("connect");
ConnectArgs = (host, port, transport, allowInsecure, timeoutMs);
ConnectCertCallback = serverCertificateValidationCallback;
if (_throwOnConnect)
@@ -130,8 +214,12 @@ internal sealed class FakeLdapConnection : ILdapConnection
public void Bind(string dn, string password)
{
BindAttempts++;
Calls.Add($"bind:{dn}");
var isServiceBind = BindAttempts == 1;
if (isServiceBind && _firstBindResultCode is { } code)
throw new Novell.Directory.Ldap.LdapException("Bind refused", code, dn);
if ((_throwOnServiceBind && isServiceBind)
|| (_throwOnUserBind && !isServiceBind)
|| _throwBindDns.Contains(dn))
@@ -147,7 +235,33 @@ internal sealed class FakeLdapConnection : ILdapConnection
string searchBase,
string filter,
IReadOnlyList<string> attributes)
=> _scriptedEntries.AsReadOnly();
{
Calls.Add($"search:{filter}");
SearchAttributes = attributes;
if (_throwOnSearch)
throw new Novell.Directory.Ldap.LdapException(
"Search failed", Novell.Directory.Ldap.LdapException.Unavailable, searchBase);
return _filterResults.TryGetValue(filter, out var scripted) ? scripted : _scriptedEntries.AsReadOnly();
}
public LdapSearchEntry? Read(string dn, IReadOnlyList<string> attributes)
{
Calls.Add($"read:{dn}");
if (_throwOnRead)
throw new Novell.Directory.Ldap.LdapException(
"Read failed", Novell.Directory.Ldap.LdapException.InsufficientAccessRights, dn);
var attrs = new Dictionary<string, IReadOnlyList<string>>(StringComparer.OrdinalIgnoreCase);
if (_principalName is not null)
attrs["msDS-PrincipalName"] = new[] { _principalName };
return new LdapSearchEntry(dn, attrs);
}
public string WhoAmI()
{
Calls.Add("whoami");
return _whoAmI ?? throw new Novell.Directory.Ldap.LdapException(
"Protocol Error", Novell.Directory.Ldap.LdapException.ProtocolError, null);
}
public void Dispose() { /* nothing to clean up */ }
}
@@ -0,0 +1,159 @@
// GLAuth integration tests for the 0.5.0 passwordless group lookup — opt-in only.
//
// Same gate and variables as GLAuthIntegrationTests (ZB_LDAP_IT=1, ZB_LDAP_SERVER/PORT/BASE,
// ZB_LDAP_SVC_DN/PW, ZB_LDAP_USER/PW, ZB_LDAP_USERATTR). ZB_LDAP_FALLBACK (optional, "host:port")
// names a second live directory for the two-live-endpoint failover case — e.g. the redundant local
// pair in scadaproj/infra/glauth-redundant (primary :3893, backup :3894):
//
// ZB_LDAP_IT=1 ZB_LDAP_SERVER=localhost ZB_LDAP_PORT=3893 ZB_LDAP_FALLBACK=localhost:3894 \
// ZB_LDAP_BASE=dc=zb,dc=local ZB_LDAP_SVC_DN=cn=serviceaccount,dc=zb,dc=local ZB_LDAP_SVC_PW=... \
// ZB_LDAP_USER=multi-role ZB_LDAP_PW=... \
// dotnet test tests/ZB.MOM.WW.Auth.Ldap.Tests --filter "FullyQualifiedName~GLAuthGroupLookupTests"
using System.Net.Sockets;
using ZB.MOM.WW.Auth.Abstractions.Ldap;
namespace ZB.MOM.WW.Auth.Ldap.Tests.Integration;
public sealed class GLAuthGroupLookupTests
{
private sealed record Env(string Server, int Port, string BaseDn, string SvcDn, string SvcPw,
string User, string Pw, string UserAttr, string? Fallback);
private static Env Require()
{
Skip.IfNot(Environment.GetEnvironmentVariable("ZB_LDAP_IT") == "1", "Set ZB_LDAP_IT=1 and a reachable GLAuth to run.");
var env = new Env(
Environment.GetEnvironmentVariable("ZB_LDAP_SERVER") ?? "localhost",
int.TryParse(Environment.GetEnvironmentVariable("ZB_LDAP_PORT"), out var p) ? p : 3893,
Environment.GetEnvironmentVariable("ZB_LDAP_BASE") ?? "dc=lmxopcua,dc=local",
Environment.GetEnvironmentVariable("ZB_LDAP_SVC_DN") ?? "",
Environment.GetEnvironmentVariable("ZB_LDAP_SVC_PW") ?? "",
Environment.GetEnvironmentVariable("ZB_LDAP_USER") ?? "",
Environment.GetEnvironmentVariable("ZB_LDAP_PW") ?? "",
Environment.GetEnvironmentVariable("ZB_LDAP_USERATTR") ?? "cn",
Environment.GetEnvironmentVariable("ZB_LDAP_FALLBACK"));
try
{
using var tcp = new TcpClient();
if (!tcp.ConnectAsync(env.Server, env.Port).Wait(TimeSpan.FromSeconds(3)))
Skip.If(true, $"GLAuth not reachable at {env.Server}:{env.Port} (connect timed out).");
}
catch (Exception ex)
{
Skip.If(true, $"GLAuth not reachable at {env.Server}:{env.Port}: {ex.Message}");
}
return env;
}
private static LdapOptions Options(Env env) => new()
{
Enabled = true,
Server = env.Server,
Port = env.Port,
Transport = LdapTransport.None,
AllowInsecure = true,
SearchBase = env.BaseDn,
ServiceAccountDn = env.SvcDn,
ServiceAccountPassword = env.SvcPw,
UserNameAttribute = env.UserAttr,
GroupAttribute = "memberOf",
ConnectionTimeoutMs = 3000,
};
/// <summary>The lookup returns exactly the group set, username and display name a real sign-in does.</summary>
[SkippableFact]
public async Task Lookup_ReturnsTheSameGroupsAsSignIn()
{
var env = Require();
var svc = new LdapAuthService(Options(env));
var login = await svc.AuthenticateAsync(env.User, env.Pw, CancellationToken.None);
var lookup = await svc.GetUserGroupsAsync(env.User, CancellationToken.None);
Assert.True(login.Succeeded, $"sign-in failed: {login.Failure}");
Assert.Equal(LdapGroupLookupStatus.Found, lookup.Status);
Assert.NotEmpty(lookup.Groups);
Assert.Equal(login.Groups.OrderBy(g => g, StringComparer.Ordinal), lookup.Groups.OrderBy(g => g, StringComparer.Ordinal));
Assert.Equal(login.Username, lookup.Username);
Assert.Equal(login.DisplayName, lookup.DisplayName);
}
[SkippableFact]
public async Task Lookup_OfAnUnknownName_IsUserNotFound()
{
var env = Require();
var svc = new LdapAuthService(Options(env));
var lookup = await svc.GetUserGroupsAsync("no-such-user-" + Guid.NewGuid().ToString("N")[..8], CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.UserNotFound, lookup.Status);
}
/// <summary>A wrong service-account password is the directory refusing US, not the user: DirectoryUnavailable.</summary>
[SkippableFact]
public async Task Lookup_WithAWrongServiceAccountPassword_IsDirectoryUnavailable()
{
var env = Require();
var svc = new LdapAuthService(Options(env) with { ServiceAccountPassword = "definitely-wrong" });
var lookup = await svc.GetUserGroupsAsync(env.User, CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.DirectoryUnavailable, lookup.Status);
}
/// <summary>Dead primary (closed local port) fails over to the live directory, twice (sticky).</summary>
[SkippableFact]
public async Task Lookup_FailsOverFromADeadPrimary()
{
var env = Require();
var svc = new LdapAuthService(Options(env) with
{
Server = "127.0.0.1",
Port = 39999,
FallbackServers = new[] { $"{env.Server}:{env.Port}" },
});
var first = await svc.GetUserGroupsAsync(env.User, CancellationToken.None);
var second = await svc.GetUserGroupsAsync(env.User, CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.Found, first.Status);
Assert.Equal(LdapGroupLookupStatus.Found, second.Status);
}
/// <summary>Every endpoint dead: DirectoryUnavailable, never UserNotFound (which would revoke a session).</summary>
[SkippableFact]
public async Task Lookup_WithEveryEndpointDead_IsDirectoryUnavailable()
{
var env = Require();
var svc = new LdapAuthService(Options(env) with
{
Server = "127.0.0.1",
Port = 39999,
FallbackServers = new[] { "127.0.0.1:39998" },
});
var lookup = await svc.GetUserGroupsAsync(env.User, CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.DirectoryUnavailable, lookup.Status);
}
/// <summary>Two LIVE directories (ZB_LDAP_FALLBACK): primary answers first; a dead primary port walks to the backup.</summary>
[SkippableFact]
public async Task Lookup_AcrossTwoLiveDirectories_AnswersFromEither()
{
var env = Require();
Skip.If(string.IsNullOrWhiteSpace(env.Fallback), "Set ZB_LDAP_FALLBACK=host:port to a second live directory.");
var both = new LdapAuthService(Options(env) with { FallbackServers = new[] { env.Fallback! } });
var backupOnly = new LdapAuthService(Options(env) with { Port = 39999, Server = "127.0.0.1", FallbackServers = new[] { env.Fallback! } });
var viaPrimary = await both.GetUserGroupsAsync(env.User, CancellationToken.None);
var viaBackup = await backupOnly.GetUserGroupsAsync(env.User, CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.Found, viaPrimary.Status);
Assert.Equal(LdapGroupLookupStatus.Found, viaBackup.Status);
Assert.Equal(viaPrimary.Groups.OrderBy(g => g), viaBackup.Groups.OrderBy(g => g));
}
}
@@ -99,4 +99,70 @@ public sealed class GLAuthIntegrationTests
$"Authentication failed: {result.Failure} (server={server}:{port}, user={user})");
Assert.NotEmpty(result.Groups);
}
/// <summary>
/// Failover: primary endpoint points at a closed local port (refused immediately),
/// fallback at the real GLAuth. The login must succeed via the fallback, and a second
/// login must also succeed (sticky preference — no re-walk through the dead primary).
/// Skipped unless <c>ZB_LDAP_IT=1</c> is set; skipped again if the server is unreachable.
/// </summary>
[SkippableFact]
public async Task Authenticate_FailsOverFromDeadPrimary_ToRealGLAuth()
{
// ------------------------------------------------------------------ opt-in gate
Skip.IfNot(
Environment.GetEnvironmentVariable("ZB_LDAP_IT") == "1",
"Set ZB_LDAP_IT=1 and a reachable GLAuth to run.");
// ------------------------------------------------------------------ read config
var server = Environment.GetEnvironmentVariable("ZB_LDAP_SERVER") ?? "localhost";
var port = int.TryParse(Environment.GetEnvironmentVariable("ZB_LDAP_PORT"), out var p) ? p : 3893;
var baseDn = Environment.GetEnvironmentVariable("ZB_LDAP_BASE") ?? "dc=lmxopcua,dc=local";
var svcDn = Environment.GetEnvironmentVariable("ZB_LDAP_SVC_DN") ?? "";
var svcPw = Environment.GetEnvironmentVariable("ZB_LDAP_SVC_PW") ?? "";
var user = Environment.GetEnvironmentVariable("ZB_LDAP_USER") ?? "";
var pw = Environment.GetEnvironmentVariable("ZB_LDAP_PW") ?? "";
var userAttr = Environment.GetEnvironmentVariable("ZB_LDAP_USERATTR") ?? "cn";
// ------------------------------------------------------------------ reachability probe
try
{
using var tcp = new TcpClient();
// 3-second connect timeout to keep the test suite snappy when the server is absent
var connectTask = tcp.ConnectAsync(server, port);
if (!connectTask.Wait(TimeSpan.FromSeconds(3)))
Skip.If(true, $"GLAuth not reachable at {server}:{port} (connect timed out).");
}
catch (Exception ex)
{
Skip.If(true, $"GLAuth not reachable at {server}:{port}: {ex.Message}");
}
// ------------------------------------------------------------------ build options
var options = new LdapOptions
{
Enabled = true,
Server = "127.0.0.1",
Port = 39999, // closed port -> immediate refusal
Transport = LdapTransport.None,
AllowInsecure = true,
SearchBase = baseDn,
ServiceAccountDn = svcDn,
ServiceAccountPassword = svcPw,
UserNameAttribute = userAttr,
GroupAttribute = "memberOf",
ConnectionTimeoutMs = 3000,
FallbackServers = new[] { $"{server}:{port}" },
};
// ------------------------------------------------------------------ exercise the real service
var svc = new LdapAuthService(options);
var first = await svc.AuthenticateAsync(user, pw, CancellationToken.None);
Assert.True(first.Succeeded, $"first login failed: {first.Failure}");
// Second login exercises the sticky preference: it must not re-walk the dead primary.
var second = await svc.AuthenticateAsync(user, pw, CancellationToken.None);
Assert.True(second.Succeeded, $"second login failed: {second.Failure}");
}
}
@@ -0,0 +1,85 @@
// Live user-bind identity test (Auth-007, scadaproj#40) — opt-in only.
//
// Start the throwaway fixture (NOT the shared rig — it needs users that can search):
// cd tests/ZB.MOM.WW.Auth.Ldap.Tests/Integration/glauth-userbind && docker compose up -d
// Run:
// ZB_LDAP_USERBIND_IT=1 dotnet test tests/ZB.MOM.WW.Auth.Ldap.Tests \
// --filter "FullyQualifiedName~GLAuthUserBindIdentityTests"
// Optional: ZB_LDAP_USERBIND_SERVER (default localhost), ZB_LDAP_USERBIND_PORT (default 3897).
//
// GLAuth does not implement RFC 4532 Who-am-I (it answers protocol error 2), so these tests also
// prove the DN-template fallback path against a real directory.
using System.Net.Sockets;
using ZB.MOM.WW.Auth.Abstractions.Ldap;
namespace ZB.MOM.WW.Auth.Ldap.Tests.Integration;
public sealed class GLAuthUserBindIdentityTests
{
private static LdapOptions Options(string template, string userNameAttribute)
{
var server = Environment.GetEnvironmentVariable("ZB_LDAP_USERBIND_SERVER") ?? "localhost";
var port = int.TryParse(Environment.GetEnvironmentVariable("ZB_LDAP_USERBIND_PORT"), out var p) ? p : 3897;
try
{
using var tcp = new TcpClient();
if (!tcp.ConnectAsync(server, port).Wait(TimeSpan.FromSeconds(3)))
Skip.If(true, $"GLAuth fixture not reachable at {server}:{port}.");
}
catch (Exception ex)
{
Skip.If(true, $"GLAuth fixture not reachable at {server}:{port}: {ex.Message}");
}
return new LdapOptions
{
Server = server,
Port = port,
Transport = LdapTransport.None,
AllowInsecure = true,
SearchBase = "dc=zb,dc=local",
BindMode = LdapBindMode.User,
UserBindTemplate = template,
UserNameAttribute = userNameAttribute,
GroupAttribute = "memberOf",
ConnectionTimeoutMs = 3000,
};
}
/// <summary>
/// mallory binds with her own password; <c>(mail=mallory)</c> finds the <c>boss</c> entry, which
/// is in Admins. Before the fix this signed mallory in with boss's groups.
/// </summary>
[SkippableFact]
public async Task BoundAccount_DifferentFromTheSearchedEntry_IsRefused()
{
Skip.IfNot(Environment.GetEnvironmentVariable("ZB_LDAP_USERBIND_IT") == "1",
"Set ZB_LDAP_USERBIND_IT=1 and start Integration/glauth-userbind to run.");
var svc = new LdapAuthService(Options("cn={0},ou=Users,dc=zb,dc=local", "mail"));
var result = await svc.AuthenticateAsync("mallory", "password", CancellationToken.None);
Assert.False(result.Succeeded, $"signed in as {result.Username} with [{string.Join(",", result.Groups)}]");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
Assert.DoesNotContain("Admins", result.Groups);
}
/// <summary>Positive control: the same mechanism admits a user whose bind DN is the entry's DN.</summary>
[SkippableFact]
public async Task BoundAccount_SameAsTheSearchedEntry_Succeeds()
{
Skip.IfNot(Environment.GetEnvironmentVariable("ZB_LDAP_USERBIND_IT") == "1",
"Set ZB_LDAP_USERBIND_IT=1 and start Integration/glauth-userbind to run.");
// GLAuth reports search DNs as cn=<user>,ou=<group>,ou=users,<base>; it also accepts that
// form as a bind DN, so this template binds the exact DN the search returns.
var svc = new LdapAuthService(Options("cn={0},ou=Users,ou=users,dc=zb,dc=local", "cn"));
var result = await svc.AuthenticateAsync("boss", "password", CancellationToken.None);
Assert.True(result.Succeeded, $"failed: {result.Failure}");
Assert.Equal("boss", result.Username);
Assert.Contains("Admins", result.Groups);
}
}
@@ -0,0 +1,49 @@
# GLAuth fixture for the user-bind identity test (Auth-007, scadaproj#40).
# Start: docker compose up -d (listens on localhost:3897)
# All passwords are "password" (sha256 below).
#
# mallory binds as herself (cn=mallory,ou=Users,...). The admin entry carries mail=mallory,
# so with UserNameAttribute=mail a search for the typed name "mallory" finds the ADMIN — the
# account that bound and the account searched for differ. The library must refuse.
[ldap]
enabled = true
listen = "0.0.0.0:3893"
[ldaps]
enabled = false
[backend]
datastore = "config"
baseDN = "dc=zb,dc=local"
[behaviors]
LimitFailedBinds = false
[[groups]]
name = "Users"
gidnumber = 6001
[[groups]]
name = "Admins"
gidnumber = 6002
[[users]]
name = "mallory"
mail = "mallory-real@zb.local"
uidnumber = 6101
primarygroup = 6001
passsha256 = "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
[[users.capabilities]]
action = "search"
object = "*"
[[users]]
name = "boss"
mail = "mallory"
uidnumber = 6102
primarygroup = 6001
othergroups = [6002]
passsha256 = "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
[[users.capabilities]]
action = "search"
object = "*"
@@ -0,0 +1,10 @@
# Throwaway GLAuth for GLAuthUserBindIdentityTests (Auth-007). Not the shared rig.
name: zb-auth-userbind-it
services:
glauth:
image: glauth/glauth:latest
container_name: zb-auth-userbind-it
ports:
- "3897:3893"
volumes:
- ./config.toml:/app/config/config.cfg:ro
@@ -0,0 +1,297 @@
using ZB.MOM.WW.Auth.Abstractions.Ldap;
namespace ZB.MOM.WW.Auth.Ldap.Tests;
/// <summary>
/// Covers the multi-endpoint failover walk: which failures fail over (system-side only),
/// which are final (any authoritative answer from a healthy directory), how the sticky
/// endpoint preference moves, and that single-endpoint behaviour is unchanged.
/// </summary>
public class LdapAuthServiceFailoverTests
{
private static LdapOptions Opts(params string[] fallbacks) => new()
{
Enabled = true,
Server = "dc1",
Port = 636,
Transport = LdapTransport.Ldaps,
SearchBase = "dc=x",
ServiceAccountDn = "cn=svc,dc=x",
ServiceAccountPassword = "svcpw",
FallbackServers = fallbacks,
};
private static FakeLdapConnection HealthyWithUser() =>
new FakeLdapConnection().WithUserEntry("cn=alice,dc=x", new[] { "cn=ops,dc=x" });
// ---- failover triggers (system-side) ----
[Fact]
public async Task ConnectFailure_FailsOverToFallback_AndSucceeds()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnConnect(), HealthyWithUser());
var svc = new LdapAuthService(Opts("dc2:3894"), factory);
var result = await svc.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.True(result.Succeeded);
Assert.Equal(2, factory.Created.Count);
Assert.Equal("dc1", factory.Created[0].ConnectArgs!.Value.Host);
Assert.Equal("dc2", factory.Created[1].ConnectArgs!.Value.Host);
Assert.Equal(3894, factory.Created[1].ConnectArgs!.Value.Port);
}
[Fact]
public async Task ServiceBindFailure_FailsOverToFallback()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnServiceBind(), HealthyWithUser());
var svc = new LdapAuthService(Opts("dc2"), factory);
var result = await svc.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.True(result.Succeeded);
Assert.Equal(636, factory.Created[1].ConnectArgs!.Value.Port); // bare host adopts Port
}
// ---- user-side results NEVER fail over ----
[Fact]
public async Task BadUserCredentials_DoesNotFailOver()
{
var factory = new SequenceLdapConnectionFactory(
HealthyWithUser().ThrowOnUserBind());
var svc = new LdapAuthService(Opts("dc2"), factory);
var result = await svc.AuthenticateAsync("alice", "wrong", CancellationToken.None);
Assert.Equal(LdapAuthFailure.BadCredentials, result.Failure);
Assert.Single(factory.Created);
}
[Fact]
public async Task UserNotFound_DoesNotFailOver()
{
var factory = new SequenceLdapConnectionFactory(new FakeLdapConnection());
var svc = new LdapAuthService(Opts("dc2"), factory);
var result = await svc.AuthenticateAsync("ghost", "pw", CancellationToken.None);
Assert.Equal(LdapAuthFailure.UserNotFound, result.Failure);
Assert.Single(factory.Created);
}
[Fact]
public async Task GroupLookupFailed_DoesNotFailOver()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().WithUserEntry("cn=alice,dc=x", Array.Empty<string>()));
var svc = new LdapAuthService(Opts("dc2"), factory);
var result = await svc.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
Assert.Single(factory.Created);
}
[Fact]
public async Task AmbiguousUser_DoesNotFailOver()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().WithDuplicateMatch());
var svc = new LdapAuthService(Opts("dc2"), factory);
var result = await svc.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.Equal(LdapAuthFailure.AmbiguousUser, result.Failure);
Assert.Single(factory.Created);
}
// ---- exhaustion ----
[Fact]
public async Task AllEndpointsDown_ReturnsServiceAccountBindFailed()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnConnect(),
new FakeLdapConnection().ThrowOnConnect());
var svc = new LdapAuthService(Opts("dc2"), factory);
var result = await svc.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.Equal(LdapAuthFailure.ServiceAccountBindFailed, result.Failure);
Assert.Equal(2, factory.Created.Count);
}
// ---- stickiness ----
[Fact]
public async Task StickyPreference_SecondLoginStartsAtLastGoodEndpoint()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnConnect(), // login 1 @ dc1: dead
HealthyWithUser(), // login 1 @ dc2: answers
HealthyWithUser()); // login 2: should go straight to dc2
var svc = new LdapAuthService(Opts("dc2"), factory);
Assert.True((await svc.AuthenticateAsync("alice", "pw", CancellationToken.None)).Succeeded);
Assert.True((await svc.AuthenticateAsync("alice", "pw", CancellationToken.None)).Succeeded);
Assert.Equal(3, factory.Created.Count);
Assert.Equal("dc2", factory.Created[2].ConnectArgs!.Value.Host);
}
[Fact]
public async Task StickyPreference_DriftsBackToPrimary_WhenPreferredFails()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnConnect(), // login 1 @ dc1: dead
HealthyWithUser(), // login 1 @ dc2: answers -> preferred
new FakeLdapConnection().ThrowOnConnect(), // login 2 @ dc2: now dead
HealthyWithUser(), // login 2 @ dc1 (declared order): recovered
HealthyWithUser()); // login 3: should start at dc1 again
var svc = new LdapAuthService(Opts("dc2"), factory);
Assert.True((await svc.AuthenticateAsync("alice", "pw", CancellationToken.None)).Succeeded);
Assert.True((await svc.AuthenticateAsync("alice", "pw", CancellationToken.None)).Succeeded);
Assert.True((await svc.AuthenticateAsync("alice", "pw", CancellationToken.None)).Succeeded);
Assert.Equal(5, factory.Created.Count);
Assert.Equal("dc1", factory.Created[3].ConnectArgs!.Value.Host);
Assert.Equal("dc1", factory.Created[4].ConnectArgs!.Value.Host);
}
[Fact]
public async Task StickyPreference_UpdatesOnUserSideAnswer_NotOnlySuccess()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnConnect(), // login 1 @ dc1: dead
new FakeLdapConnection(), // login 1 @ dc2: answers UserNotFound
HealthyWithUser()); // login 2: should start at dc2
var svc = new LdapAuthService(Opts("dc2"), factory);
var first = await svc.AuthenticateAsync("ghost", "pw", CancellationToken.None);
Assert.Equal(LdapAuthFailure.UserNotFound, first.Failure);
Assert.True((await svc.AuthenticateAsync("alice", "pw", CancellationToken.None)).Succeeded);
Assert.Equal("dc2", factory.Created[2].ConnectArgs!.Value.Host);
}
[Fact]
public async Task AllEndpointsDown_LeavesPreferenceUnchanged()
{
// A total outage teaches nothing about which endpoint is healthy, so the walk
// must not move the preference — the next login still starts at the primary.
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnConnect(), // login 1 @ dc1
new FakeLdapConnection().ThrowOnConnect(), // login 1 @ dc2
HealthyWithUser()); // login 2: must start at dc1 again
var svc = new LdapAuthService(Opts("dc2"), factory);
Assert.Equal(LdapAuthFailure.ServiceAccountBindFailed,
(await svc.AuthenticateAsync("alice", "pw", CancellationToken.None)).Failure);
Assert.True((await svc.AuthenticateAsync("alice", "pw", CancellationToken.None)).Succeeded);
Assert.Equal("dc1", factory.Created[2].ConnectArgs!.Value.Host);
}
// ---- back-compat ----
[Fact]
public async Task NoFallbacks_SingleAttempt_UnchangedBehavior()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnConnect());
var svc = new LdapAuthService(Opts(/* no fallbacks */), factory);
var result = await svc.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.Equal(LdapAuthFailure.ServiceAccountBindFailed, result.Failure);
Assert.Single(factory.Created);
}
[Fact]
public async Task Disabled_NeverOpensAConnection_EvenWithFallbacks()
{
var factory = new SequenceLdapConnectionFactory(HealthyWithUser());
var svc = new LdapAuthService(Opts("dc2") with { Enabled = false }, factory);
var result = await svc.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.Equal(LdapAuthFailure.Disabled, result.Failure);
Assert.Empty(factory.Created);
}
[Fact]
public async Task MalformedFallbackEntry_IsSkippedDefensively()
{
// The validator rejects this at boot; a service constructed without validation
// must degrade to the parseable subset, not throw.
var factory = new SequenceLdapConnectionFactory(HealthyWithUser());
var svc = new LdapAuthService(Opts(":::"), factory);
Assert.True((await svc.AuthenticateAsync("alice", "pw", CancellationToken.None)).Succeeded);
Assert.Single(factory.Created);
}
// ---- observability ----
/// <summary>Captures emitted log entries so failover visibility can be asserted.</summary>
private sealed class RecordingLogger : Microsoft.Extensions.Logging.ILogger<LdapAuthService>
{
public List<(Microsoft.Extensions.Logging.LogLevel Level, string Message)> Entries { get; } = new();
public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
public bool IsEnabled(Microsoft.Extensions.Logging.LogLevel logLevel) => true;
public void Log<TState>(Microsoft.Extensions.Logging.LogLevel logLevel, Microsoft.Extensions.Logging.EventId eventId,
TState state, Exception? exception, Func<TState, Exception?, string> formatter)
=> Entries.Add((logLevel, formatter(state, exception)));
}
[Fact]
public async Task Failover_LogsWarningWithEndpointAndStage_AndInfoOnStickyChange()
{
var logger = new RecordingLogger();
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnConnect(), HealthyWithUser());
var svc = new LdapAuthService(Opts("dc2:3894"), factory, logger);
await svc.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.Contains(logger.Entries, e =>
e.Level == Microsoft.Extensions.Logging.LogLevel.Warning
&& e.Message.Contains("dc1:636") && e.Message.Contains("connect"));
Assert.Contains(logger.Entries, e =>
e.Level == Microsoft.Extensions.Logging.LogLevel.Information
&& e.Message.Contains("dc2:3894"));
// Never log secrets:
Assert.DoesNotContain(logger.Entries, e => e.Message.Contains("svcpw") || e.Message.Contains("pw\""));
}
[Fact]
public async Task HappyPath_LogsNothing()
{
var logger = new RecordingLogger();
var factory = new SequenceLdapConnectionFactory(HealthyWithUser());
var svc = new LdapAuthService(Opts("dc2"), factory, logger);
await svc.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.Empty(logger.Entries);
}
[Fact]
public async Task ServiceBindFailure_LogsTheServiceBindStage_NotConnect()
{
var logger = new RecordingLogger();
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnServiceBind(), HealthyWithUser());
var svc = new LdapAuthService(Opts("dc2"), factory, logger);
await svc.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.Contains(logger.Entries, e =>
e.Level == Microsoft.Extensions.Logging.LogLevel.Warning
&& e.Message.Contains("dc1:636") && e.Message.Contains("service-bind"));
}
}
@@ -147,4 +147,93 @@ public class LdapAuthServiceTests
Assert.True(r.Succeeded);
Assert.Equal(new[] { "Eng,ineers", "A,B" }, r.Groups);
}
[Fact]
public async Task Username_IsCanonicalisedFromTheEntry_InServiceAccountMode()
{
var fake = new FakeLdapConnection().WithUserEntry(
"cn=alice,dc=x", new[] { "cn=g,dc=x" }, "Alice",
new Dictionary<string, string[]> { ["cn"] = new[] { "alice" } });
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(fake));
var r = await svc.AuthenticateAsync("ALICE", "pw", default);
Assert.True(r.Succeeded);
Assert.Equal("alice", r.Username);
}
[Fact]
public async Task Username_FallsBackToTheTypedName_InServiceAccountMode_WhenAttributeAbsent()
{
var fake = new FakeLdapConnection().WithUserEntry("cn=alice,dc=x", new[] { "cn=g,dc=x" }, "Alice");
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(fake));
var r = await svc.AuthenticateAsync("ALICE", "pw", default);
Assert.True(r.Succeeded);
Assert.Equal("ALICE", r.Username);
}
// ---- Auth-009 (scadaproj#46): a multi-valued UserNameAttribute ----------------------------
[Fact]
public async Task Username_FromAMultiValuedAttribute_IsTheValueTheUserMatched()
{
// OpenLDAP / 389-DS entries routinely carry both cn values; the server's ordering decides
// which comes first. The search matched "jsmith", so that is the identity, not "John Smith".
var fake = new FakeLdapConnection().WithUserEntry(
"cn=jsmith,dc=x", new[] { "cn=g,dc=x" }, "John",
new Dictionary<string, string[]> { ["cn"] = new[] { "John Smith", "jsmith" } });
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(fake));
var r = await svc.AuthenticateAsync("jsmith", "pw", default);
Assert.True(r.Succeeded);
Assert.Equal("jsmith", r.Username);
}
[Fact]
public async Task Username_FromAMultiValuedAttribute_StillTakesTheDirectorysCase()
{
var fake = new FakeLdapConnection().WithUserEntry(
"cn=jsmith,dc=x", new[] { "cn=g,dc=x" }, "John",
new Dictionary<string, string[]> { ["cn"] = new[] { "John Smith", "JSmith" } });
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(fake));
var r = await svc.AuthenticateAsync("jsmith", "pw", default);
Assert.True(r.Succeeded);
Assert.Equal("JSmith", r.Username);
}
[Fact]
public async Task Username_FallsBackToTheFirstValue_WhenNoValueMatchesTheTypedName()
{
// The directory matched on something the attribute values do not spell the same way
// (a matching rule beyond case, say): keep 0.4.1's first-value behaviour.
var fake = new FakeLdapConnection().WithUserEntry(
"cn=jsmith,dc=x", new[] { "cn=g,dc=x" }, "John",
new Dictionary<string, string[]> { ["cn"] = new[] { "J. Smith", "John Smith" } });
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(fake));
var r = await svc.AuthenticateAsync("jsmith", "pw", default);
Assert.True(r.Succeeded);
Assert.Equal("J. Smith", r.Username);
}
[Theory]
[InlineData("")]
[InlineData(null)]
public async Task EmptyPassword_IsRefused_InServiceAccountMode_WithoutContactingTheDirectory(string? password)
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().WithUserEntry("cn=alice,dc=x", new[] { "cn=g,dc=x" }, "Alice"));
var svc = new LdapAuthService(Opts(), factory);
var r = await svc.AuthenticateAsync("alice", password!, default);
Assert.Equal(LdapAuthFailure.BadCredentials, r.Failure);
Assert.Empty(factory.Created);
}
}
@@ -0,0 +1,478 @@
using Novell.Directory.Ldap;
using ZB.MOM.WW.Auth.Abstractions.Ldap;
namespace ZB.MOM.WW.Auth.Ldap.Tests;
/// <summary>
/// <see cref="LdapBindMode.User"/>: bind as the signing-in user, then read their own entry on the
/// same connection. The service account in <see cref="Opts"/> is deliberately populated so the
/// tests prove it is never used.
/// </summary>
public class LdapAuthServiceUserBindTests
{
private static LdapOptions Opts(params string[] fallbacks) => new()
{
Enabled = true,
Server = "dc1",
Port = 636,
Transport = LdapTransport.Ldaps,
SearchBase = "dc=x",
UserNameAttribute = "sAMAccountName",
DisplayNameAttribute = "displayName",
GroupAttribute = "memberOf",
BindMode = LdapBindMode.User,
UserBindTemplate = "{0}@corp.test",
ServiceAccountDn = "cn=svc,dc=x",
ServiceAccountPassword = "svcpw",
FallbackServers = fallbacks,
};
private const string JaneDn = "CN=Jane Doe,OU=u,DC=x";
private static FakeLdapConnection Jane() => new FakeLdapConnection()
.WithWhoAmI("dn:" + JaneDn)
.WithUserEntry(JaneDn, new[] { "CN=UG_A,OU=g,DC=x", "CN=UG_B,OU=g,DC=x" }, "Jane Doe");
private static Task<LdapAuthResult> Login(LdapAuthService svc, string user, string pw = "pw") =>
svc.AuthenticateAsync(user, pw, CancellationToken.None);
[Fact]
public async Task Success_BindsAsUser_ThenSearchesOnTheSameConnection()
{
var factory = new SequenceLdapConnectionFactory(Jane());
var result = await Login(new LdapAuthService(Opts(), factory), "jdoe");
Assert.True(result.Succeeded);
Assert.Equal("jdoe", result.Username);
Assert.Equal("Jane Doe", result.DisplayName);
Assert.Equal(new[] { "UG_A", "UG_B" }, result.Groups);
var conn = Assert.Single(factory.Created);
Assert.Equal(new[] { "connect", "bind:jdoe@corp.test", "whoami", "search:(sAMAccountName=jdoe)" }, conn.Calls);
Assert.Equal(new[] { "jdoe@corp.test" }, conn.BoundDns);
}
[Theory]
[InlineData(@"NAM\jdoe")]
[InlineData("jdoe@corp.test")]
[InlineData(" jdoe ")]
public async Task QualifiedNames_BindAsTheTemplate_AndReturnTheBareName(string typed)
{
var factory = new SequenceLdapConnectionFactory(Jane());
var result = await Login(new LdapAuthService(Opts(), factory), typed);
Assert.True(result.Succeeded);
Assert.Equal("jdoe", result.Username);
Assert.Equal(new[] { "jdoe@corp.test" }, factory.Created[0].BoundDns);
}
[Fact]
public async Task EmptyPassword_IsRefused_WithoutContactingTheDirectory()
{
var factory = new SequenceLdapConnectionFactory(Jane());
var result = await Login(new LdapAuthService(Opts(), factory), "jdoe", "");
Assert.Equal(LdapAuthFailure.BadCredentials, result.Failure);
Assert.Empty(factory.Created);
}
[Theory]
[InlineData("@x")]
[InlineData(@"a\b\c")]
[InlineData("a@b@c")]
public async Task UnusableNames_AreRefused_WithoutContactingTheDirectory(string typed)
{
var factory = new SequenceLdapConnectionFactory(Jane());
var result = await Login(new LdapAuthService(Opts(), factory), typed);
Assert.Equal(LdapAuthFailure.BadCredentials, result.Failure);
Assert.Empty(factory.Created);
}
[Fact]
public async Task StrictMode_RefusesQualifiedNames_WithoutContactingTheDirectory()
{
var factory = new SequenceLdapConnectionFactory(Jane());
var svc = new LdapAuthService(Opts() with { AcceptDomainQualifiedNames = false }, factory);
var result = await Login(svc, @"NAM\jdoe");
Assert.Equal(LdapAuthFailure.BadCredentials, result.Failure);
Assert.Empty(factory.Created);
}
[Fact]
public async Task WrongPassword_IsFinal_AndNeverAsksTheFallback()
{
var factory = new SequenceLdapConnectionFactory(
Jane().ThrowOnFirstBind(LdapException.InvalidCredentials), Jane());
var result = await Login(new LdapAuthService(Opts("dc2"), factory), "jdoe", "wrong");
Assert.Equal(LdapAuthFailure.BadCredentials, result.Failure);
Assert.Single(factory.Created);
}
[Fact]
public async Task NonCredentialBindError_FailsOver()
{
var factory = new SequenceLdapConnectionFactory(
Jane().ThrowOnFirstBind(LdapException.Unavailable), Jane());
var result = await Login(new LdapAuthService(Opts("dc2"), factory), "jdoe");
Assert.True(result.Succeeded);
Assert.Equal(2, factory.Created.Count);
Assert.Equal("dc2", factory.Created[1].ConnectArgs!.Value.Host);
}
[Fact]
public async Task ConnectFailure_FailsOver()
{
var factory = new SequenceLdapConnectionFactory(new FakeLdapConnection().ThrowOnConnect(), Jane());
var result = await Login(new LdapAuthService(Opts("dc2"), factory), "jdoe");
Assert.True(result.Succeeded);
Assert.Equal(2, factory.Created.Count);
}
[Fact]
public async Task SearchFailure_FailsOver()
{
var factory = new SequenceLdapConnectionFactory(Jane().ThrowOnSearch(), Jane());
var result = await Login(new LdapAuthService(Opts("dc2"), factory), "jdoe");
Assert.True(result.Succeeded);
Assert.Equal(2, factory.Created.Count);
}
[Fact]
public async Task EveryEndpointDown_IsSystemSide()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnConnect(), new FakeLdapConnection().ThrowOnConnect());
var result = await Login(new LdapAuthService(Opts("dc2"), factory), "jdoe");
Assert.Equal(LdapAuthFailure.ServiceAccountBindFailed, result.Failure);
}
[Fact]
public async Task NoEntryAfterAGoodBind_IsGroupLookupFailed()
{
var factory = new SequenceLdapConnectionFactory(new FakeLdapConnection().WithWhoAmI("dn:" + JaneDn).WithNoMatch());
var result = await Login(new LdapAuthService(Opts("dc2"), factory), "jdoe");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
Assert.Single(factory.Created);
}
[Fact]
public async Task TwoEntriesAfterAGoodBind_IsGroupLookupFailed()
{
var factory = new SequenceLdapConnectionFactory(new FakeLdapConnection().WithWhoAmI("dn:cn=dup1,dc=x").WithDuplicateMatch());
var result = await Login(new LdapAuthService(Opts(), factory), "jdoe");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
}
[Fact]
public async Task NoGroups_IsGroupLookupFailed()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().WithWhoAmI("dn:CN=Jane,DC=x").WithUserEntry("CN=Jane,DC=x", Array.Empty<string>(), "Jane"));
var result = await Login(new LdapAuthService(Opts(), factory), "jdoe");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
}
[Fact]
public async Task Username_IsCanonicalisedFromTheEntry_NotTheTypedCase()
{
var factory = new SequenceLdapConnectionFactory(new FakeLdapConnection().WithWhoAmI(@"u:NAM\jdoe").WithUserEntry(
"CN=Jane Doe,OU=u,DC=x", new[] { "CN=UG_A,OU=g,DC=x" }, "Jane Doe",
new Dictionary<string, string[]> { ["sAMAccountName"] = new[] { "jdoe" } }));
var result = await Login(new LdapAuthService(Opts(), factory), @"NAM\JDOE");
Assert.True(result.Succeeded);
Assert.Equal("jdoe", result.Username);
}
[Fact]
public async Task Username_FallsBackToTheTypedName_WhenTheEntryLacksTheAttribute()
{
var factory = new SequenceLdapConnectionFactory(Jane());
var result = await Login(new LdapAuthService(Opts(), factory), "JDOE");
Assert.True(result.Succeeded);
Assert.Equal("JDOE", result.Username);
}
[Fact]
public async Task Search_RequestsTheUserNameAttribute()
{
var factory = new SequenceLdapConnectionFactory(Jane());
await Login(new LdapAuthService(Opts(), factory), "jdoe");
Assert.Equal(new[] { "displayName", "memberOf", "sAMAccountName" }, factory.Created[0].SearchAttributes);
}
[Fact]
public async Task Search_DeDuplicatesTheUserNameAttribute_CaseInsensitively()
{
var factory = new SequenceLdapConnectionFactory(Jane());
var svc = new LdapAuthService(Opts() with { DisplayNameAttribute = "SAMACCOUNTNAME" }, factory);
await Login(svc, "jdoe");
Assert.Equal(new[] { "SAMACCOUNTNAME", "memberOf" }, factory.Created[0].SearchAttributes);
}
// ---- Auth-007 (scadaproj#40): the entry whose groups are returned must be the account that bound ----
/// <summary>
/// The review's scenario: a UPN bind for <c>jsmith</c> is resolved by AD to Mallory (explicit UPN
/// <c>jsmith@corp.test</c>, sAMAccountName <c>jsmith2</c>), while <c>(sAMAccountName=jsmith)</c>
/// finds the admin. Before the fix this returned the admin's groups to Mallory.
/// </summary>
[Fact]
public async Task UpnBind_ResolvedToAnotherAccount_DoesNotReturnTheSearchedEntrysGroups()
{
var fake = new FakeLdapConnection()
.WithWhoAmI(@"u:CORP\jsmith2")
.WithUserEntry("CN=Admin Smith,OU=u,DC=x", new[] { "CN=UG_Admins,OU=g,DC=x" }, "Admin Smith",
new Dictionary<string, string[]> { ["sAMAccountName"] = new[] { "jsmith" } });
var factory = new SequenceLdapConnectionFactory(fake);
var result = await Login(new LdapAuthService(Opts(), factory), "jsmith", "mallorys-own-password");
Assert.False(result.Succeeded);
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
Assert.Empty(result.Groups);
Assert.Equal(new[] { "jsmith@corp.test" }, fake.BoundDns);
}
[Fact]
public async Task WhoAmIAccountName_MatchingTheEntry_Succeeds_AndRequestsSamAccountName()
{
var fake = new FakeLdapConnection()
.WithWhoAmI(@"u:CORP\JSmith")
.WithUserEntry("CN=John Smith,OU=u,DC=x", new[] { "CN=UG_A,OU=g,DC=x" }, "John Smith",
new Dictionary<string, string[]> { ["sAMAccountName"] = new[] { "jsmith" } });
var factory = new SequenceLdapConnectionFactory(fake);
var svc = new LdapAuthService(Opts() with { UserNameAttribute = "cn" }, factory);
var result = await Login(svc, "John Smith");
Assert.True(result.Succeeded);
Assert.Contains("sAMAccountName", fake.SearchAttributes!);
}
[Fact]
public async Task WhoAmIAccountName_WithoutDomain_IsAccepted()
{
var fake = new FakeLdapConnection()
.WithWhoAmI("u:jdoe")
.WithUserEntry(JaneDn, new[] { "CN=UG_A,OU=g,DC=x" }, "Jane Doe",
new Dictionary<string, string[]> { ["sAMAccountName"] = new[] { "jdoe" } });
var result = await Login(new LdapAuthService(Opts(), new SequenceLdapConnectionFactory(fake)), "jdoe");
Assert.True(result.Succeeded);
}
[Fact]
public async Task WhoAmIAccountName_EntryWithoutSamAccountName_FailsClosed()
{
var fake = new FakeLdapConnection()
.WithWhoAmI(@"u:CORP\jdoe")
.WithUserEntry(JaneDn, new[] { "CN=UG_A,OU=g,DC=x" }, "Jane Doe");
var result = await Login(new LdapAuthService(Opts(), new SequenceLdapConnectionFactory(fake)), "jdoe");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
}
// ---- scadaproj#50: an AD forest — the same sAMAccountName in two domains ----------------------
// A Global Catalog search base spans every domain in the forest. CORP\jsmith binds; the search
// (here on mail, so the filter is not sAMAccountName) finds OTHER\jsmith, whose sAMAccountName is
// also "jsmith". 0.4.4 compared sAMAccountName alone and returned OTHER\jsmith's groups.
private const string OtherDn = "CN=J Smith,OU=u,DC=other,DC=forest";
private const string CorpDn = "CN=John Smith,OU=u,DC=corp,DC=forest";
private static FakeLdapConnection ForestSearchFinding(string dn) => new FakeLdapConnection()
.WithWhoAmI(@"u:CORP\jsmith")
.WithUserEntry(dn, new[] { "CN=UG_Admins,OU=g,DC=other,DC=forest" }, "J Smith",
new Dictionary<string, string[]> { ["sAMAccountName"] = new[] { "jsmith" }, ["mail"] = new[] { "jsmith" } });
private static LdapOptions ForestOpts() => Opts() with { UserNameAttribute = "mail", SearchBase = "DC=forest" };
[Fact]
public async Task Forest_PrincipalNameInAnotherDomain_FailsClosed()
{
var fake = ForestSearchFinding(OtherDn).WithPrincipalName(@"OTHER\jsmith");
var result = await Login(new LdapAuthService(ForestOpts(), new SequenceLdapConnectionFactory(fake)), "jsmith");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
Assert.Empty(result.Groups);
Assert.Contains("read:" + OtherDn, fake.Calls);
}
[Fact]
public async Task Forest_PrincipalNameInTheBoundDomain_Succeeds()
{
var fake = ForestSearchFinding(CorpDn).WithPrincipalName(@"corp\JSMITH");
var result = await Login(new LdapAuthService(ForestOpts(), new SequenceLdapConnectionFactory(fake)), "jsmith");
Assert.True(result.Succeeded);
}
[Fact]
public async Task Forest_NoPrincipalName_AndTheNameIsHeldInTwoDomains_FailsClosed()
{
// The directory offers no msDS-PrincipalName, so which jsmith bound cannot be proven; with two
// holders of the name in scope the sign-in is refused rather than guessed.
var fake = ForestSearchFinding(OtherDn)
.WithSearchResult("(sAMAccountName=jsmith)", (CorpDn, "jsmith"), (OtherDn, "jsmith"));
var result = await Login(new LdapAuthService(ForestOpts(), new SequenceLdapConnectionFactory(fake)), "jsmith");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
}
[Fact]
public async Task Forest_NoPrincipalName_AndTheReadFails_StillFallsBackToTheUniquenessCheck()
{
var fake = ForestSearchFinding(OtherDn).ThrowOnRead()
.WithSearchResult("(sAMAccountName=jsmith)", (CorpDn, "jsmith"), (OtherDn, "jsmith"));
var result = await Login(new LdapAuthService(ForestOpts(), new SequenceLdapConnectionFactory(fake)), "jsmith");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
}
[Fact]
public async Task SingleDomain_NoPrincipalName_UniqueName_Succeeds()
{
// Compatibility: a single-domain directory without msDS-PrincipalName still signs in — the
// name has exactly one holder in scope, and it is the entry found.
var fake = ForestSearchFinding(CorpDn).WithSearchResult("(sAMAccountName=jsmith)", (CorpDn, "jsmith"));
var result = await Login(new LdapAuthService(ForestOpts(), new SequenceLdapConnectionFactory(fake)), "jsmith");
Assert.True(result.Succeeded);
}
[Fact]
public async Task SamAccountNameSearch_ForTheBoundName_NeedsNoSecondSearch()
{
// When the user search itself was (sAMAccountName=<the bound name>) and found exactly one
// entry, the name is already proven unique in scope.
var fake = new FakeLdapConnection()
.WithWhoAmI(@"u:CORP\jdoe")
.WithUserEntry(JaneDn, new[] { "CN=UG_A,OU=g,DC=x" }, "Jane Doe",
new Dictionary<string, string[]> { ["sAMAccountName"] = new[] { "jdoe" } });
var result = await Login(new LdapAuthService(Opts(), new SequenceLdapConnectionFactory(fake)), "jdoe");
Assert.True(result.Succeeded);
Assert.Single(fake.Calls, c => c.StartsWith("search:", StringComparison.Ordinal));
}
[Fact]
public async Task WhoAmIDn_NamingAnotherEntry_FailsClosed()
{
var fake = new FakeLdapConnection()
.WithWhoAmI("dn:CN=Mallory,OU=u,DC=x")
.WithUserEntry("CN=Admin Smith,OU=u,DC=x", new[] { "CN=UG_Admins,OU=g,DC=x" }, "Admin Smith");
var result = await Login(new LdapAuthService(Opts(), new SequenceLdapConnectionFactory(fake)), "jsmith");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
Assert.Empty(result.Groups);
}
[Fact]
public async Task WhoAmIDn_IsComparedAsADn_NotAsAString()
{
var fake = new FakeLdapConnection()
.WithWhoAmI("dn:cn=jane doe, ou=U, dc=X")
.WithUserEntry(JaneDn, new[] { "CN=UG_A,OU=g,DC=x" }, "Jane Doe");
var result = await Login(new LdapAuthService(Opts(), new SequenceLdapConnectionFactory(fake)), "jdoe");
Assert.True(result.Succeeded);
}
[Theory]
[InlineData(null)] // server does not support Who-am-I (GLAuth: protocol error 2)
[InlineData("")] // anonymous / empty answer
[InlineData("x:garbage")]
public async Task UpnTemplate_WithoutAWhoAmIAnswer_FailsClosed_WithoutSearching(string? whoAmI)
{
var fake = new FakeLdapConnection()
.WithUserEntry(JaneDn, new[] { "CN=UG_A,OU=g,DC=x" }, "Jane Doe");
if (whoAmI is not null)
fake.WithWhoAmI(whoAmI);
var result = await Login(new LdapAuthService(Opts(), new SequenceLdapConnectionFactory(fake)), "jdoe");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
Assert.DoesNotContain(fake.Calls, c => c.StartsWith("search:", StringComparison.Ordinal));
}
[Fact]
public async Task DownLevelTemplate_WithoutAWhoAmIAnswer_FailsClosed()
{
var fake = new FakeLdapConnection()
.WithUserEntry(JaneDn, new[] { "CN=UG_A,OU=g,DC=x" }, "Jane Doe");
var svc = new LdapAuthService(Opts() with { UserBindTemplate = @"CORP\{0}" }, new SequenceLdapConnectionFactory(fake));
var result = await Login(svc, "jdoe");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
}
[Fact]
public async Task DnTemplate_WithoutWhoAmI_AcceptsTheEntryAtTheBoundDn()
{
var fake = new FakeLdapConnection()
.WithUserEntry("cn=jdoe,ou=Users,dc=x", new[] { "cn=UG_A,ou=g,dc=x" }, "Jane Doe");
var svc = new LdapAuthService(
Opts() with { UserBindTemplate = "cn={0},ou=users,dc=x", UserNameAttribute = "cn" },
new SequenceLdapConnectionFactory(fake));
var result = await Login(svc, "jdoe");
Assert.True(result.Succeeded);
}
[Fact]
public async Task DnTemplate_WithoutWhoAmI_RefusesAnEntryAtAnotherDn()
{
// Mallory binds as cn=mallory with her own password; (mail=mallory) finds the admin.
var fake = new FakeLdapConnection()
.WithUserEntry("cn=admin,ou=Users,dc=x", new[] { "cn=UG_Admins,ou=g,dc=x" }, "Admin");
var svc = new LdapAuthService(
Opts() with { UserBindTemplate = "cn={0},ou=users,dc=x", UserNameAttribute = "mail" },
new SequenceLdapConnectionFactory(fake));
var result = await Login(svc, "mallory");
Assert.Equal(LdapAuthFailure.GroupLookupFailed, result.Failure);
Assert.Equal(new[] { "cn=mallory,ou=users,dc=x" }, fake.BoundDns);
}
[Fact]
public async Task DnTemplate_EscapesTheName_SoItCannotRewriteTheBindDn()
{
var fake = new FakeLdapConnection()
.WithUserEntry("cn=admin,ou=Admins,dc=x", new[] { "cn=UG_Admins,ou=g,dc=x" }, "Admin");
var svc = new LdapAuthService(
Opts() with { UserBindTemplate = "cn={0},ou=users,dc=x", UserNameAttribute = "cn" },
new SequenceLdapConnectionFactory(fake));
var result = await Login(svc, "admin,ou=Admins");
Assert.Equal(new[] { @"cn=admin\,ou=Admins,ou=users,dc=x" }, fake.BoundDns);
Assert.False(result.Succeeded);
}
}
@@ -0,0 +1,35 @@
using ZB.MOM.WW.Auth.Ldap.Internal;
namespace ZB.MOM.WW.Auth.Ldap.Tests;
public class LdapEndpointParserTests
{
[Theory]
[InlineData("dc2.example.com", 636, "dc2.example.com", 636)] // bare host -> default port
[InlineData("dc2.example.com:3894", 636, "dc2.example.com", 3894)] // explicit port wins
[InlineData(" dc2.example.com : 3894 ", 636, "dc2.example.com", 3894)] // whitespace tolerated
public void TryParse_ValidEntry_Succeeds(string entry, int defaultPort, string host, int port)
{
Assert.True(LdapEndpointParser.TryParse(entry, defaultPort, out var ep, out _));
Assert.Equal(host, ep.Host);
Assert.Equal(port, ep.Port);
}
[Theory]
[InlineData("")] // empty
[InlineData(" ")] // whitespace
[InlineData(":636")] // empty host
[InlineData("dc2:0")] // port below range
[InlineData("dc2:65536")] // port above range
[InlineData("dc2:abc")] // non-numeric port
[InlineData("2001:db8::1:636")] // IPv6 literal (unsupported, >1 colon)
public void TryParse_InvalidEntry_Fails(string entry)
{
Assert.False(LdapEndpointParser.TryParse(entry, 636, out _, out var error));
Assert.NotEmpty(error);
}
[Fact]
public void Endpoint_ToString_IsHostColonPort() =>
Assert.Equal("dc2:3894", new LdapEndpoint("dc2", 3894).ToString());
}
@@ -0,0 +1,342 @@
using ZB.MOM.WW.Auth.Abstractions.Ldap;
namespace ZB.MOM.WW.Auth.Ldap.Tests;
/// <summary>
/// 0.5.0 passwordless group lookup (<see cref="ILdapGroupLookup"/>): statuses, parity with
/// <see cref="LdapAuthService.AuthenticateAsync"/>'s group set, the shared failover walk, and the
/// configurations that cannot search without a password.
/// </summary>
public class LdapGroupLookupTests
{
private static LdapOptions Opts(params string[] fallbacks) => new()
{
Enabled = true,
Server = "dc1",
Port = 636,
Transport = LdapTransport.Ldaps,
SearchBase = "dc=x",
ServiceAccountDn = "cn=svc,dc=x",
ServiceAccountPassword = "svcpw",
UserNameAttribute = "sAMAccountName",
DisplayNameAttribute = "displayName",
FallbackServers = fallbacks,
};
private static FakeLdapConnection Alice(string? userAccountControl = null)
{
var extra = new Dictionary<string, string[]> { ["sAMAccountName"] = new[] { "Alice" } };
if (userAccountControl is not null)
extra["userAccountControl"] = new[] { userAccountControl };
return new FakeLdapConnection().WithUserEntry(
"cn=Alice,ou=people,dc=x",
new[] { "cn=Operators,ou=g,dc=x", @"cn=Eng\,ineers,ou=g,dc=x" },
displayName: "Alice Smith",
extraAttributes: extra);
}
// ---- the happy path and parity with AuthenticateAsync ----
[Fact]
public async Task Found_ReturnsCanonicalNameDisplayNameAndGroups_WithServiceAccountOnly()
{
var fake = Alice();
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(fake));
var result = await svc.GetUserGroupsAsync(" alice ", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.Found, result.Status);
Assert.True(result.IsFound);
Assert.Equal("Alice", result.Username); // directory spelling, not the typed one
Assert.Equal("Alice Smith", result.DisplayName);
Assert.Equal(new[] { "Operators", "Eng,ineers" }, result.Groups);
// Exactly one bind, as the service account — never a bind as the user.
Assert.Equal(new[] { "cn=svc,dc=x" }, fake.BoundDns);
Assert.Equal(1, fake.BindAttempts);
Assert.Contains("search:(sAMAccountName=alice)", fake.Calls);
Assert.Contains("userAccountControl", fake.SearchAttributes!);
}
[Fact]
public async Task Found_MatchesTheGroupSetAuthenticateAsyncReturns()
{
var lookup = await new LdapAuthService(Opts(), new FakeLdapConnectionFactory(Alice()))
.GetUserGroupsAsync("alice", CancellationToken.None);
var login = await new LdapAuthService(Opts(), new FakeLdapConnectionFactory(Alice()))
.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.True(login.Succeeded);
Assert.Equal(login.Groups, lookup.Groups);
Assert.Equal(login.Username, lookup.Username);
Assert.Equal(login.DisplayName, lookup.DisplayName);
}
[Fact]
public async Task Found_WithZeroGroups_IsFoundWithAnEmptySet()
{
var fake = new FakeLdapConnection().WithUserEntry("cn=bob,dc=x", Array.Empty<string>());
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(fake));
var result = await svc.GetUserGroupsAsync("bob", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.Found, result.Status);
Assert.Empty(result.Groups);
}
// ---- directory answers ----
[Fact]
public async Task NoEntry_IsUserNotFound()
{
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(new FakeLdapConnection().WithNoMatch()));
var result = await svc.GetUserGroupsAsync("ghost", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.UserNotFound, result.Status);
Assert.Empty(result.Groups);
Assert.Equal("", result.Username);
}
[Fact]
public async Task TwoEntries_IsAmbiguousUser()
{
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(new FakeLdapConnection().WithDuplicateMatch()));
var result = await svc.GetUserGroupsAsync("dup", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.AmbiguousUser, result.Status);
Assert.Empty(result.Groups);
}
[Theory]
[InlineData("514")] // NORMAL_ACCOUNT | ACCOUNTDISABLE
[InlineData("66050")] // + DONT_EXPIRE_PASSWORD
[InlineData("2")]
public async Task AccountDisableFlag_IsUserDisabled_AndReturnsNoGroups(string uac)
{
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(Alice(uac)));
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.UserDisabled, result.Status);
Assert.Empty(result.Groups);
}
[Theory]
[InlineData("512")] // NORMAL_ACCOUNT
[InlineData("66048")] // + DONT_EXPIRE_PASSWORD
[InlineData("garbage")] // unparseable is "not disabled", never a fault
public async Task EnabledOrUnparseableAccountControl_IsFound(string uac)
{
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(Alice(uac)));
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.Found, result.Status);
}
// ---- system-side faults and failover ----
[Fact]
public async Task ConnectFailure_OnOnlyEndpoint_IsDirectoryUnavailable()
{
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(new FakeLdapConnection().ThrowOnConnect()));
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.DirectoryUnavailable, result.Status);
}
[Fact]
public async Task ServiceBindFailure_IsDirectoryUnavailable_NotUserNotFound()
{
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(Alice().ThrowOnServiceBind()));
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.DirectoryUnavailable, result.Status);
}
[Fact]
public async Task SearchFailure_IsDirectoryUnavailable()
{
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(Alice().ThrowOnSearch()));
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.DirectoryUnavailable, result.Status);
}
[Fact]
public async Task ConnectFailure_FailsOverToFallback_AndFindsTheUser()
{
var factory = new SequenceLdapConnectionFactory(new FakeLdapConnection().ThrowOnConnect(), Alice());
var svc = new LdapAuthService(Opts("dc2:3894"), factory);
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.Found, result.Status);
Assert.Equal(2, factory.Created.Count);
Assert.Equal(("dc2", 3894), (factory.Created[1].ConnectArgs!.Value.Host, factory.Created[1].ConnectArgs!.Value.Port));
}
[Fact]
public async Task SearchFailure_FailsOverToFallback()
{
var factory = new SequenceLdapConnectionFactory(Alice().ThrowOnSearch(), Alice());
var svc = new LdapAuthService(Opts("dc2"), factory);
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.Found, result.Status);
Assert.Equal(2, factory.Created.Count);
}
[Fact]
public async Task UserNotFound_IsFinal_AndDoesNotFailOver()
{
var factory = new SequenceLdapConnectionFactory(new FakeLdapConnection(), Alice());
var svc = new LdapAuthService(Opts("dc2"), factory);
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.UserNotFound, result.Status);
Assert.Single(factory.Created);
}
[Fact]
public async Task AllEndpointsDown_IsDirectoryUnavailable_AfterTryingEach()
{
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnConnect(), new FakeLdapConnection().ThrowOnServiceBind());
var svc = new LdapAuthService(Opts("dc2"), factory);
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.DirectoryUnavailable, result.Status);
Assert.Equal(2, factory.Created.Count);
}
[Fact]
public async Task StickyPreference_IsSharedWithAuthentication()
{
// A lookup that fails over to dc2 makes dc2 preferred for the next sign-in too.
var factory = new SequenceLdapConnectionFactory(
new FakeLdapConnection().ThrowOnConnect(), Alice(), Alice());
var svc = new LdapAuthService(Opts("dc2"), factory);
await svc.GetUserGroupsAsync("alice", CancellationToken.None);
var login = await svc.AuthenticateAsync("alice", "pw", CancellationToken.None);
Assert.True(login.Succeeded);
Assert.Equal(3, factory.Created.Count);
Assert.Equal("dc2", factory.Created[2].ConnectArgs!.Value.Host);
}
[Fact]
public async Task UsesConfiguredTransportTimeoutAndCertificatePolicy()
{
System.Net.Security.RemoteCertificateValidationCallback callback = (_, _, _, _) => true;
var fake = Alice();
var options = Opts() with { Transport = LdapTransport.StartTls, ConnectionTimeoutMs = 1234, ServerCertificateValidationCallback = callback };
var svc = new LdapAuthService(options, new FakeLdapConnectionFactory(fake));
await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapTransport.StartTls, fake.ConnectArgs!.Value.Transport);
Assert.Equal(1234, fake.ConnectArgs!.Value.TimeoutMs);
Assert.Same(callback, fake.ConnectCertCallback);
}
// ---- configurations that cannot look up ----
[Fact]
public async Task UserBindMode_IsNotSupported_WithoutTouchingTheNetwork()
{
var fake = Alice();
var options = Opts() with { BindMode = LdapBindMode.User, UserBindTemplate = @"X\{0}", ServiceAccountDn = "" };
var svc = new LdapAuthService(options, new FakeLdapConnectionFactory(fake));
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.NotSupported, result.Status);
Assert.Empty(fake.Calls);
}
[Fact]
public async Task UserBindMode_IsNotSupported_EvenWithAServiceAccountConfigured()
{
var fake = Alice();
var options = Opts() with { BindMode = LdapBindMode.User, UserBindTemplate = @"X\{0}" };
var svc = new LdapAuthService(options, new FakeLdapConnectionFactory(fake));
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.NotSupported, result.Status);
Assert.Empty(fake.Calls);
}
[Fact]
public async Task BlankServiceAccount_IsNotSupported_NeverAnAnonymousBind()
{
var fake = Alice();
var svc = new LdapAuthService(Opts() with { ServiceAccountDn = " " }, new FakeLdapConnectionFactory(fake));
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.NotSupported, result.Status);
Assert.Empty(fake.Calls);
}
[Fact]
public async Task DisabledProvider_IsProviderDisabled_WithoutTouchingTheNetwork()
{
var fake = Alice();
var svc = new LdapAuthService(Opts() with { Enabled = false }, new FakeLdapConnectionFactory(fake));
var result = await svc.GetUserGroupsAsync("alice", CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.ProviderDisabled, result.Status);
Assert.Empty(fake.Calls);
}
[Theory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public async Task BlankUsername_IsUserNotFound_WithoutTouchingTheNetwork(string? username)
{
var fake = Alice();
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(fake));
var result = await svc.GetUserGroupsAsync(username!, CancellationToken.None);
Assert.Equal(LdapGroupLookupStatus.UserNotFound, result.Status);
Assert.Empty(fake.Calls);
}
[Fact]
public async Task FilterMetacharacters_AreEscaped()
{
var fake = new FakeLdapConnection();
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(fake));
await svc.GetUserGroupsAsync("*)(cn=*", CancellationToken.None);
Assert.Contains(@"search:(sAMAccountName=\2a\29\28cn=\2a)", fake.Calls);
}
[Fact]
public async Task CancelledToken_Throws()
{
var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(Alice()));
using var cts = new CancellationTokenSource();
cts.Cancel();
await Assert.ThrowsAnyAsync<OperationCanceledException>(() => svc.GetUserGroupsAsync("alice", cts.Token));
}
[Fact]
public void Of_RefusesFound()
=> Assert.Throws<ArgumentException>(() => LdapGroupLookupResult.Of(LdapGroupLookupStatus.Found));
}
@@ -88,4 +88,66 @@ public class LdapOptionsValidatorTests
ServiceAccountDn = "",
})
.Failed);
[Fact]
public void Validator_Succeeds_WithValidFallbackServers() =>
Assert.False(new LdapOptionsValidator()
.Validate(null, Opts() with { FallbackServers = new[] { "dc2", "dc3:3894" } })
.Failed);
[Theory]
[InlineData("")]
[InlineData(":636")]
[InlineData("dc2:0")]
[InlineData("dc2:notaport")]
public void Validator_Fails_OnMalformedFallbackServer(string entry)
{
var result = new LdapOptionsValidator()
.Validate(null, Opts() with { FallbackServers = new[] { entry } });
Assert.True(result.Failed);
Assert.Contains(nameof(LdapOptions.FallbackServers), result.FailureMessage);
}
[Fact]
public void Validator_Skips_FallbackServers_WhenDisabled() =>
// Same inert-when-disabled rule as every other connection field: a disabled
// provider never opens a connection, so its fallback list is never walked.
Assert.False(new LdapOptionsValidator()
.Validate(null, Opts() with { Enabled = false, FallbackServers = new[] { ":::" } })
.Failed);
private static LdapOptions UserOpts() => Opts() with
{
BindMode = LdapBindMode.User,
UserBindTemplate = "{0}@corp.test",
ServiceAccountDn = "",
ServiceAccountPassword = "",
};
[Fact]
public void Defaults_KeepServiceAccountMode()
{
var o = new LdapOptions();
Assert.Equal(LdapBindMode.ServiceAccount, o.BindMode);
Assert.Equal("", o.UserBindTemplate);
Assert.True(o.AcceptDomainQualifiedNames);
}
[Fact]
public void Validator_UserMode_DoesNotRequireServiceAccount() =>
Assert.True(new LdapOptionsValidator().Validate(null, UserOpts()).Succeeded);
[Theory]
[InlineData("")]
[InlineData(" ")]
[InlineData("jdoe@corp.test")]
[InlineData("{0}{0}@corp.test")]
public void Validator_UserMode_RequiresExactlyOnePlaceholder(string template)
{
var result = new LdapOptionsValidator().Validate(null, UserOpts() with { UserBindTemplate = template });
Assert.True(result.Failed);
Assert.Contains(nameof(LdapOptions.UserBindTemplate), result.FailureMessage, StringComparison.Ordinal);
}
}
@@ -0,0 +1,47 @@
using ZB.MOM.WW.Auth.Ldap.Internal;
namespace ZB.MOM.WW.Auth.Ldap.Tests;
public class LdapUserNameTests
{
[Theory]
[InlineData("jdoe")]
[InlineData(" jdoe ")]
[InlineData(@"NAM\jdoe")]
[InlineData("jdoe@corp.test")]
public void Accepting_ReducesToBareName(string input)
{
Assert.True(LdapUserName.TryNormalize(input, acceptDomainQualified: true, out var name));
Assert.Equal("jdoe", name);
}
[Theory]
[InlineData(@"NAM\jdoe")]
[InlineData("jdoe@corp.test")]
public void Strict_RefusesQualifiedNames(string input) =>
Assert.False(LdapUserName.TryNormalize(input, acceptDomainQualified: false, out _));
[Fact]
public void Strict_AcceptsBareName()
{
Assert.True(LdapUserName.TryNormalize(" jdoe ", acceptDomainQualified: false, out var name));
Assert.Equal("jdoe", name);
}
[Theory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
[InlineData("@x")]
[InlineData(@"\jdoe")]
[InlineData("jdoe@")]
[InlineData(@"NAM\")]
[InlineData(@"a\b\c")]
[InlineData("a@b@c")]
[InlineData(@"NAM\jdoe@corp.test")]
public void Unusable_IsRefused(string? input)
{
Assert.False(LdapUserName.TryNormalize(input, acceptDomainQualified: true, out var name));
Assert.Equal("", name);
}
}
@@ -0,0 +1,179 @@
using Novell.Directory.Ldap;
using Xunit;
using ZB.MOM.WW.Auth.Ldap.Internal;
namespace ZB.MOM.WW.Auth.Ldap.Tests;
/// <summary>
/// Covers <see cref="NovellLdapConnection.ReadEntries"/>' handling of AD continuation
/// referrals. Active Directory returns one for any search based at a domain root, and
/// Novell surfaces it by throwing from <c>Next()</c>. Before this was handled, the
/// exception escaped the search stage and every login against
/// <c>DC=nam,DC=zimmer,DC=com</c> failed as <c>ServiceAccountBindFailed</c> while the
/// directory and credentials were healthy.
/// </summary>
public sealed class NovellSearchReferralTests
{
[Fact]
public void Referral_before_the_only_entry_does_not_lose_it()
{
var results = new ScriptedResults(
Step.Referral(),
Step.Entry("CN=dohertj2,OU=Office Users,OU=Warsaw,DC=nam,DC=zimmer,DC=com"));
var entries = NovellLdapConnection.ReadEntries(results);
var entry = Assert.Single(entries);
Assert.Equal("CN=dohertj2,OU=Office Users,OU=Warsaw,DC=nam,DC=zimmer,DC=com", entry.Dn);
}
[Fact]
public void Referral_after_the_entry_does_not_discard_what_was_already_read()
{
var results = new ScriptedResults(
Step.Entry("CN=a,DC=nam,DC=zimmer,DC=com"),
Step.Referral());
var entries = NovellLdapConnection.ReadEntries(results);
Assert.Equal("CN=a,DC=nam,DC=zimmer,DC=com", Assert.Single(entries).Dn);
}
/// <summary>
/// The real shape observed against the NAM domain root: several references interleaved
/// with the one user entry. All three of AD's usual continuation points are present.
/// </summary>
[Fact]
public void Multiple_interleaved_referrals_still_yield_every_entry()
{
var results = new ScriptedResults(
Step.Referral(),
Step.Entry("CN=a,DC=nam,DC=zimmer,DC=com"),
Step.Referral(),
Step.Referral(),
Step.Entry("CN=b,DC=nam,DC=zimmer,DC=com"));
var entries = NovellLdapConnection.ReadEntries(results);
Assert.Equal(["CN=a,DC=nam,DC=zimmer,DC=com", "CN=b,DC=nam,DC=zimmer,DC=com"],
entries.Select(e => e.Dn));
}
/// <summary>
/// A referral-only result set is a legitimate "nothing here" answer, and must come back
/// empty rather than throwing — <c>LdapAuthService</c> reads empty as <c>UserNotFound</c>,
/// which is the honest verdict, where an exception would become a system-side failure.
/// </summary>
[Fact]
public void Referrals_only_returns_empty_rather_than_throwing()
{
var results = new ScriptedResults(Step.Referral(), Step.Referral());
Assert.Empty(NovellLdapConnection.ReadEntries(results));
}
/// <summary>
/// A base <see cref="LdapException"/> carrying the Referral result code is treated the
/// same as the derived type — the catch filter must not depend on the exact class.
/// </summary>
[Fact]
public void Referral_result_code_on_a_base_exception_is_also_skipped()
{
var results = new ScriptedResults(
Step.Throwing(new LdapException("referral", LdapException.Referral, null)),
Step.Entry("CN=a,DC=nam,DC=zimmer,DC=com"));
Assert.Single(NovellLdapConnection.ReadEntries(results));
}
/// <summary>
/// Only referrals are swallowed. A genuine directory fault must still propagate so the
/// caller maps it to a system-side failure — silently returning a short result set would
/// turn "the directory is broken" into "no such user", which is the wrong answer to give
/// about someone's credentials.
/// </summary>
[Fact]
public void A_non_referral_fault_still_propagates()
{
var results = new ScriptedResults(
Step.Throwing(new LdapException("busy", LdapException.Busy, null)),
Step.Entry("CN=a,DC=nam,DC=zimmer,DC=com"));
var ex = Assert.Throws<LdapException>(() => NovellLdapConnection.ReadEntries(results));
Assert.Equal(LdapException.Busy, ex.ResultCode);
}
/// <summary>
/// A pathological client that throws a referral without advancing must not spin forever
/// inside a fail-closed authentication path.
/// </summary>
[Fact]
public void An_endless_referral_stream_terminates()
{
var results = new EndlessReferrals();
var entries = NovellLdapConnection.ReadEntries(results);
Assert.Empty(entries);
Assert.InRange(results.Calls, 1, 2_000);
}
// ---------------------------------------------------------------------
private sealed record Step(LdapEntry? Value, Exception? Throw)
{
public static Step Entry(string dn) => new(new LdapEntry(dn, new LdapAttributeSet()), null);
public static Step Referral() => new(null, new LdapReferralException("continuation reference"));
public static Step Throwing(Exception ex) => new(null, ex);
}
/// <summary>Replays a fixed script of entries and faults through the Novell result seam.</summary>
private sealed class ScriptedResults : ILdapSearchResults
{
private readonly Step[] _steps;
private int _index;
public ScriptedResults(params Step[] steps) => _steps = steps;
public int Count => _steps.Length;
public LdapControl[] ResponseControls => [];
public bool HasMore() => _index < _steps.Length;
public LdapEntry Next()
{
var step = _steps[_index++];
if (step.Throw is not null) throw step.Throw;
return step.Value!;
}
// The production reader drives HasMore()/Next() directly; enumeration is part of the
// interface but not part of the path under test.
public IEnumerator<LdapEntry> GetEnumerator() => throw new NotSupportedException();
System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() => GetEnumerator();
}
/// <summary>Always claims more results and always throws a referral, never advancing.</summary>
private sealed class EndlessReferrals : ILdapSearchResults
{
public int Calls { get; private set; }
public int Count => int.MaxValue;
public LdapControl[] ResponseControls => [];
public bool HasMore() => true;
public LdapEntry Next()
{
Calls++;
throw new LdapReferralException("continuation reference");
}
public IEnumerator<LdapEntry> GetEnumerator() => throw new NotSupportedException();
System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() => GetEnumerator();
}
}
@@ -0,0 +1,51 @@
using ZB.MOM.WW.Auth.Ldap.Internal;
namespace ZB.MOM.WW.Auth.Ldap.Tests;
/// <summary>
/// Test double for <see cref="ILdapConnectionFactory"/> that hands out pre-scripted
/// <see cref="FakeLdapConnection"/> instances in order, one per <see cref="Create"/> call —
/// exactly matching the failover walk, which opens a fresh connection per endpoint attempt.
/// Records every created connection for inspection. When the script runs out, returns a
/// bare unscripted fake (which yields user-not-found) so a miscounted test fails loudly
/// rather than reusing a stale fake.
/// </summary>
internal sealed class SequenceLdapConnectionFactory : ILdapConnectionFactory
{
private readonly Queue<FakeLdapConnection> _script;
/// <summary>Scripts the connections handed out, in the order the walk will request them.</summary>
public SequenceLdapConnectionFactory(params FakeLdapConnection[] fakes)
=> _script = new Queue<FakeLdapConnection>(fakes);
/// <summary>Every connection handed out, in creation order (scripted or overflow).</summary>
public List<FakeLdapConnection> Created { get; } = new();
/// <inheritdoc />
public ILdapConnection Create()
{
var fake = _script.Count > 0 ? _script.Dequeue() : new FakeLdapConnection();
Created.Add(fake);
return fake;
}
}
// ---------------------------------------------------------------------------
// Smoke test: verifies the sequencing and overflow behaviour the failover tests rely on.
// ---------------------------------------------------------------------------
public class SequenceLdapConnectionFactorySmokeTests
{
[Fact]
public void Create_ReturnsScriptedFakesInOrder_ThenOverflows()
{
var first = new FakeLdapConnection().ThrowOnConnect();
var second = new FakeLdapConnection();
var factory = new SequenceLdapConnectionFactory(first, second);
Assert.Same(first, factory.Create());
Assert.Same(second, factory.Create());
Assert.NotSame(second, factory.Create()); // overflow: fresh bare fake
Assert.Equal(3, factory.Created.Count);
}
}
+33 -2
View File
@@ -4,7 +4,7 @@ Startup configuration-validation library for the **ZB.MOM.WW SCADA family** (OtO
The library normalizes the three-project configuration-validation surface: a failure-accumulating `IValidateOptions` base, reusable rule primitives, a bind+validate+`ValidateOnStart` DI extension, and a pre-host `ConfigPreflight` aggregator for raw `IConfiguration` — so the plumbing is written once and domain rules stay per-project.
**Built at 0.1.0. Adopted by OtOpcUa, MxAccessGateway, and ScadaBridge on 2026-06-01** (local default branches; not yet pushed to remotes). Adoption tracked in `~/Desktop/scadaproj/components/configuration/GAPS.md`.
**Built at 0.1.0. Adopted by OtOpcUa, MxAccessGateway, and ScadaBridge on 2026-06-01, and by HistorianGateway since;** all four pin `0.1.0` (the only feed version) on their pushed origin default branches (verified 2026-11-09). Adoption tracked in `~/Desktop/scadaproj/components/configuration/GAPS.md`.
---
@@ -66,7 +66,7 @@ ZB.MOM.WW.Configuration/
## Status
Part of the **scadaproj component-normalization family** — this is the configuration + validation component. Built at **0.1.0**. **Adopted by OtOpcUa, MxAccessGateway, and ScadaBridge on 2026-06-01** (local default branches; not yet pushed to remotes) — per-app result is tracked in:
Part of the **scadaproj component-normalization family** — this is the configuration + validation component. Built at **0.1.0**. **Adopted by OtOpcUa, MxAccessGateway, and ScadaBridge on 2026-06-01** (since pushed; HistorianGateway also pins `0.1.0` — all four verified on their origin default branches 2026-11-09) — per-app result is tracked in:
- `~/Desktop/scadaproj/components/configuration/GAPS.md`
@@ -75,3 +75,34 @@ Design documentation:
- `~/Desktop/scadaproj/components/configuration/spec/SPEC.md` — normalized validation target
- `~/Desktop/scadaproj/components/configuration/shared-contract/ZB.MOM.WW.Configuration.md` — proposed shared-library API
- `~/Desktop/scadaproj/components/configuration/current-state/` — per-project current state (code-verified)
## Index history (migrated from the scadaproj root CLAUDE.md)
> Moved verbatim out of the scadaproj root `CLAUDE.md` on 2026-09-03 so it loads only when needed. **This file is now the authoritative place for this history — append new entries here and keep the root index row short.**
### Narrative
The configuration component is fully populated: a normalized [`spec`](components/configuration/spec/SPEC.md), a
[`shared-contract`](components/configuration/shared-contract/ZB.MOM.WW.Configuration.md), three
[`current-state`](components/configuration/current-state/) docs, and an adoption [`GAPS`](components/configuration/GAPS.md)
backlog. Shared = the `IValidateOptions<T>` failure-accumulation base (`OptionsValidatorBase<T>`) +
reusable rule primitives (`ValidationBuilder`: port / host:port / required / positive-duration / one-of /
min-count) + `AddValidatedOptions<TOptions,TValidator>()` (bind + validate + `ValidateOnStart`) + the
pre-host `ConfigPreflight` aggregator (generalizes ScadaBridge's `StartupValidator`, byte-compatible
message); left per-project = each app's options classes + domain rules, and OtOpcUa's
draft/generation-content validation (DB-side `sp_ValidateDraft`; its C# `DraftValidator` is dormant).
The shared library is **built and lives in this repo** at [`ZB.MOM.WW.Configuration/`](ZB.MOM.WW.Configuration/)
(.NET 10; single package `ZB.MOM.WW.Configuration`; 42 tests (verified 2026-07-18); `dotnet pack` → 1 nupkg @ 0.1.0).
The implementation plan is at
[`docs/plans/2026-06-01-zb-mom-ww-configuration-shared-library.md`](docs/plans/2026-06-01-zb-mom-ww-configuration-shared-library.md).
**Adopted across all three apps on 2026-06-01** (OtOpcUa, MxAccessGateway, ScadaBridge) on each repo's
local default branch (`main`/`master`) — merged, and since pushed to origin (the "not yet pushed" caveat this
record carried is stale; all four apps, HistorianGateway included, pin `0.1.0` on their origin default branches as of 2026-11-09); the package was first
published to the Gitea feed. Behaviour-preserving onto `OptionsValidatorBase`/`AddValidatedOptions`
for MxGateway + ScadaBridge (validator messages byte-identical), `StartupValidator` → `ConfigPreflight`
for ScadaBridge, and net-new `Ldap`/`OpcUa` validators for OtOpcUa. Per-app result tracked in
[`components/configuration/GAPS.md`](components/configuration/GAPS.md).
Build/test from `ZB.MOM.WW.Configuration/`: `dotnet test`. Consumer matrix: all three apps consume the
single package; ScadaBridge is the heaviest adopter (per-module validators + `StartupValidator` →
`ConfigPreflight`); OtOpcUa adoption is additive (it has no `IValidateOptions` usage today).
@@ -5,8 +5,8 @@
<Authors>ZB.MOM.WW</Authors>
<Description>Startup configuration-validation toolkit for the ZB.MOM.WW SCADA family: a failure-accumulating IValidateOptions base, reusable rule primitives (port, host:port, required, positive-duration, one-of, min-count), a bind+validate+ValidateOnStart DI helper, and a pre-host ConfigPreflight aggregator for raw IConfiguration. Extracts the validation plumbing the apps share; domain rules stay per-project.</Description>
<PackageTags>configuration;options;validation;ivalidateoptions;validateonstart;startup;scada;wonderware;zb-mom-ww</PackageTags>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-configuration</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-configuration</RepositoryUrl>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/scadaproj/src/branch/main/ZB.MOM.WW.Configuration</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/scadaproj</RepositoryUrl>
<PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup>
<ItemGroup>
+50
View File
@@ -0,0 +1,50 @@
# ZB.MOM.WW.GalaxyRepository
Shared Galaxy object-hierarchy SQL browse + `galaxy_repository.v1` gRPC service for the **ZB.MOM.WW SCADA family** (consumed by HistorianGateway and mxaccessgw). Build/test from this directory: `dotnet test`.
## 0.2.2 (2026-11-09, UNPUBLISHED)
Version bumped in `Directory.Build.props`, not packed or pushed. P3 review fixes (scadaproj#47):
- 003: parent cycles are broken at the lowest gobject id so their members stay browsable.
- 004: Stale threshold is `max(5 min, 3 x DashboardRefreshIntervalSeconds)` (new optional `IOptions` ctor
parameter on `GalaxyHierarchyCache`); the projected-Stale entry is memoized per source entry.
- 005: `WatchDeployEvents` subscribers never see a non-increasing `Sequence`.
- 006: container-building tests for `AddZbGalaxyRepository`.
- 007: `System.Security.Cryptography.Pkcs` pinned at 9.0.21 (clears NU1902/NU1903 for consumers).
- 008: empty `SnapshotCachePath` disables persistence (documented + logged once).
## 0.2.1 (2026-11-09, UNPUBLISHED)
Version bumped in `Directory.Build.props`, not packed or pushed; consumers stay on `0.2.0`.
- GalaxyRepository-001 (scadaproj#41): the per-cache-entry filter memos of both projectors are now
`ProjectionMemo<T>`, capped at 64 signatures (FIFO; an evicted signature is recomputed, same answer).
- GalaxyRepository-002 (scadaproj#42): a browse-subtree scope (`Plant/LineA/*`) no longer hides the
allowed subtree's ancestors. `BrowseChildren` and `DiscoverHierarchy` return them as
**navigation-only** nodes — attributes stripped, only the path to an allowed object listed, siblings
still hidden. **Behaviour change for consumers:** a scoped `DiscoverHierarchy` now includes those
ancestors (`GalaxyHierarchyQueryResult.NavigationAncestorCount` says how many); `WatchDeployEvents`
still counts allowed objects only. Semantics documented on `IGalaxyBrowseScopeProvider`.
## Index history (migrated from the scadaproj root CLAUDE.md)
> Moved verbatim out of the scadaproj root `CLAUDE.md` on 2026-09-03 so it loads only when needed. **This file is now the authoritative place for this history — append new entries here and keep the root index row short.**
### Narrative
The Galaxy Repository component normalizes the **Galaxy object-hierarchy SQL browse + reusable gRPC service**
that was previously embedded in `mxaccessgw`. Shared = canonical `galaxy_repository.v1` proto (wire-compatible
with `mxaccessgw`'s existing contract so OtOpcUa's `GalaxyRepositoryClient` is unaffected), the SQL browse
provider (`HierarchySql` / `AttributesSql` validated reverse-engineered queries), in-memory hierarchy cache +
snapshot + deploy-poll refresh `BackgroundService`, `GalaxyHierarchyProjector`, and `AddZbGalaxyRepository` /
`MapZbGalaxyRepository` DI extension. Left per-consumer = section path, subtree auth filtering, and any
app-specific paging defaults.
The shared library is **built and lives in this repo** at [`ZB.MOM.WW.GalaxyRepository/`](ZB.MOM.WW.GalaxyRepository/)
(.NET 10; single package `ZB.MOM.WW.GalaxyRepository`; `dotnet pack` → 1 nupkg @ 0.1.0, **published to
the Gitea NuGet feed** `gitea.dohertylan.com/api/packages/dohertj2/nuget`). The design doc is at
[`docs/plans/2026-06-23-historian-gateway-design.md`](docs/plans/2026-06-23-historian-gateway-design.md) (§10, component 1).
**Consumed by HistorianGateway** as a `PackageReference` from that Gitea feed, pinned at `0.2.0` (originally a
cross-repo `ProjectReference` to this scadaproj tree; switched to the feed package 2026-06-24; bumped `0.1.0` → `0.2.0` 2026-06-25).
**mxaccessgw has adopted it** (its Server calls `AddZbGalaxyRepository` / `MapZbGalaxyRepository`; the
`galaxy_repository.v1` wire contract is identical, so OtOpcUa and ScadaBridge clients are unaffected). Build/test from `ZB.MOM.WW.GalaxyRepository/`: `dotnet test`.
Consumer matrix: HistorianGateway (initial); mxaccessgw (adopted, 0.2.0).
@@ -4,7 +4,7 @@
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<LangVersion>latest</LangVersion>
<Version>0.2.0</Version>
<Version>0.2.2</Version>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
@@ -7,6 +7,11 @@
<ItemGroup>
<!-- Library -->
<PackageVersion Include="Microsoft.Data.SqlClient" Version="6.0.2" />
<!-- Transitive security pin (scadaproj#22/#47): Microsoft.Data.SqlClient 6.0.2 pulls
System.Security.Cryptography.Pkcs 9.0.4, which carries GHSA-846f-f764-76mx (high) and
GHSA-2fmv-rv2c-59x7 (moderate) and fails restore under warnings-as-errors (NU1902/NU1903).
Pin the patched 9.0.21 (first fixed in the 9.0 line). -->
<PackageVersion Include="System.Security.Cryptography.Pkcs" Version="9.0.21" />
<PackageVersion Include="Grpc.AspNetCore" Version="2.76.0" />
<!-- Google.Protobuf and Grpc.Tools must be >= the minimums Grpc.AspNetCore 2.76.0 requires -->
<PackageVersion Include="Google.Protobuf" Version="3.31.1" />
@@ -1,4 +1,3 @@
using System.Collections.Concurrent;
using System.Runtime.CompilerServices;
using System.Security.Cryptography;
using System.Text;
@@ -13,13 +12,19 @@ namespace ZB.MOM.WW.GalaxyRepository;
/// filtered child list per cache-entry instance so repeated paging is an O(pageSize)
/// slice rather than an O(siblings) filter scan per page. The memo is keyed on the
/// immutable cache entry, so when the cache publishes a new entry the stale memo
/// becomes unreachable and is reclaimed with it.
/// becomes unreachable and is reclaimed with it. Each entry's memo is capped at
/// <see cref="ProjectionMemo{TValue}.Capacity"/> signatures, because the signature is
/// client-controlled (GalaxyRepository-001).
/// </summary>
public static class GalaxyBrowseProjector
{
private static readonly ConditionalWeakTable<
GalaxyHierarchyCacheEntry,
ConcurrentDictionary<string, FilteredChildren>> FilteredChildrenCache = new();
ProjectionMemo<FilteredChildren>> FilteredChildrenCache = new();
/// <summary>Number of filter signatures currently memoized for <paramref name="entry"/> (tests).</summary>
internal static int MemoCount(GalaxyHierarchyCacheEntry entry) =>
FilteredChildrenCache.TryGetValue(entry, out var memo) ? memo.Count : 0;
/// <summary>Projects one page of direct children of the resolved parent.</summary>
/// <param name="entry">The Galaxy hierarchy cache entry to query.</param>
@@ -55,7 +60,9 @@ public static class GalaxyBrowseProjector
List<bool> hasChildren = new(Math.Max(0, end - offset));
for (int index = offset; index < end; index++)
{
page.Add(CloneObject(filtered.Children[index].Object, includeAttributes));
// A navigation-only ancestor of the browse scope never carries attributes: it is in
// the reply only so the caller can reach the allowed subtree (GalaxyRepository-002).
page.Add(CloneObject(filtered.Children[index].Object, includeAttributes && !filtered.NavigationOnly[index]));
hasChildren.Add(filtered.HasMatchingDescendant[index]);
}
@@ -115,8 +122,8 @@ public static class GalaxyBrowseProjector
int parentId,
string filterSignature)
{
ConcurrentDictionary<string, FilteredChildren> memo =
FilteredChildrenCache.GetValue(entry, static _ => new ConcurrentDictionary<string, FilteredChildren>(StringComparer.Ordinal));
ProjectionMemo<FilteredChildren> memo =
FilteredChildrenCache.GetValue(entry, static _ => new ProjectionMemo<FilteredChildren>());
return memo.GetOrAdd(
filterSignature,
@@ -129,10 +136,22 @@ public static class GalaxyBrowseProjector
List<GalaxyObjectView> matched = [];
List<bool> hasMatching = [];
List<bool> navigationOnly = [];
foreach (GalaxyObjectView view in directChildren)
{
if (!MatchesBrowseSubtrees(view, state.BrowseSubtreeGlobs))
{
// Out of scope itself, but an ancestor of an allowed object (scope
// `Plant/LineA/*` → `Plant`, `Plant/LineA`): surface it as a navigation-
// only container, or scoped lazy browse from the root is empty
// (GalaxyRepository-002). Its other children stay hidden because the same
// rule applies one level down when the caller expands it.
if (HasMatchingDescendant(view, state.Entry.Index, state.Request, state.BrowseSubtreeGlobs))
{
matched.Add(view);
hasMatching.Add(true);
navigationOnly.Add(true);
}
continue;
}
if (!MatchesFilters(view.Object, state.Request))
@@ -145,14 +164,16 @@ public static class GalaxyBrowseProjector
{
matched.Add(view);
hasMatching.Add(true);
navigationOnly.Add(false);
}
continue;
}
matched.Add(view);
hasMatching.Add(HasMatchingDescendant(view, state.Entry.Index, state.Request, state.BrowseSubtreeGlobs));
navigationOnly.Add(false);
}
return new FilteredChildren(matched, hasMatching);
return new FilteredChildren(matched, hasMatching, navigationOnly);
},
(Entry: entry, ParentId: parentId, Request: request, BrowseSubtreeGlobs: browseSubtreeGlobs));
}
@@ -277,5 +298,6 @@ public static class GalaxyBrowseProjector
private sealed record FilteredChildren(
IReadOnlyList<GalaxyObjectView> Children,
IReadOnlyList<bool> HasMatchingDescendant);
IReadOnlyList<bool> HasMatchingDescendant,
IReadOnlyList<bool> NavigationOnly);
}
@@ -60,12 +60,21 @@ public sealed class GalaxyDeployNotifier : IGalaxyDeployNotifier
channel.Writer.TryWrite(bootstrap);
}
long lastSequence = long.MinValue;
try
{
while (await channel.Reader.WaitToReadAsync(cancellationToken).ConfigureAwait(false))
{
while (channel.Reader.TryRead(out GalaxyDeployEventInfo? next))
{
// The bootstrap write can race a concurrent Publish and land behind a
// newer event; never yield an event that is not newer than the last one.
if (next.Sequence <= lastSequence)
{
continue;
}
lastSequence = next.Sequence;
yield return next;
}
}
@@ -16,17 +16,22 @@ namespace ZB.MOM.WW.GalaxyRepository;
/// </summary>
public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache, IDisposable
{
private static readonly TimeSpan StaleThreshold = TimeSpan.FromMinutes(5);
private static readonly TimeSpan MinimumStaleThreshold = TimeSpan.FromMinutes(5);
private readonly IGalaxyRepository _repository;
private readonly IGalaxyDeployNotifier _notifier;
private readonly IGalaxyHierarchySnapshotStore? _snapshotStore;
private readonly TimeProvider _timeProvider;
private readonly TimeSpan _staleThreshold;
private readonly ILogger<GalaxyHierarchyCache>? _logger;
private readonly TaskCompletionSource _firstLoad = new(TaskCreationOptions.RunContinuationsAsynchronously);
private readonly SemaphoreSlim _refreshGate = new(1, 1);
private GalaxyHierarchyCacheEntry _current = GalaxyHierarchyCacheEntry.Empty;
private bool _restoreAttempted;
private ProjectedStale? _projectedStale;
/// <summary>Memoized status-only projection so repeated reads return the same instance (keeps projector memos warm).</summary>
private sealed record ProjectedStale(GalaxyHierarchyCacheEntry Source, GalaxyHierarchyCacheEntry Projected);
/// <summary>Initializes a new instance of the <see cref="GalaxyHierarchyCache"/> class.</summary>
/// <param name="repository">Galaxy Repository client for SQL queries.</param>
@@ -37,13 +42,21 @@ public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache, IDisposable
/// Optional on-disk snapshot store. When supplied, the cache persists each
/// successful refresh and restores the last snapshot on first load.
/// </param>
/// <param name="options">
/// Optional options; the staleness threshold is <c>max(5 min, 3 x DashboardRefreshIntervalSeconds)</c>
/// so a healthy cache on a slow refresh interval is not reported Stale.
/// </param>
public GalaxyHierarchyCache(
IGalaxyRepository repository,
IGalaxyDeployNotifier notifier,
TimeProvider? timeProvider = null,
ILogger<GalaxyHierarchyCache>? logger = null,
IGalaxyHierarchySnapshotStore? snapshotStore = null)
IGalaxyHierarchySnapshotStore? snapshotStore = null,
Microsoft.Extensions.Options.IOptions<GalaxyRepositoryOptions>? options = null)
{
int refreshSeconds = options?.Value.DashboardRefreshIntervalSeconds ?? 0;
TimeSpan derived = TimeSpan.FromSeconds(Math.Max(0, refreshSeconds) * 3.0);
_staleThreshold = derived > MinimumStaleThreshold ? derived : MinimumStaleThreshold;
_repository = repository;
_notifier = notifier;
_timeProvider = timeProvider ?? TimeProvider.System;
@@ -58,9 +71,22 @@ public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache, IDisposable
{
GalaxyHierarchyCacheEntry snapshot = Volatile.Read(ref _current);
GalaxyCacheStatus projected = ProjectStatus(snapshot);
return projected == snapshot.Status
? snapshot
: snapshot with { Status = projected };
if (projected == snapshot.Status)
{
return snapshot;
}
// Reuse the projected record while the source entry is unchanged: the projectors
// memoize per entry instance, so a fresh record per read defeats the memo.
ProjectedStale? memo = Volatile.Read(ref _projectedStale);
if (memo is not null && ReferenceEquals(memo.Source, snapshot) && memo.Projected.Status == projected)
{
return memo.Projected;
}
GalaxyHierarchyCacheEntry created = snapshot with { Status = projected };
Volatile.Write(ref _projectedStale, new ProjectedStale(snapshot, created));
return created;
}
}
@@ -355,7 +381,7 @@ public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache, IDisposable
}
if (snapshot.LastSuccessAt is { } success
&& _timeProvider.GetUtcNow() - success > StaleThreshold)
&& _timeProvider.GetUtcNow() - success > _staleThreshold)
{
return GalaxyCacheStatus.Stale;
}
@@ -127,6 +127,8 @@ public sealed class GalaxyHierarchyIndex
bucket.Add(view);
}
ReRootUnreachable(views, childrenByParent);
foreach (List<GalaxyObjectView> bucket in childrenByParent.Values)
{
bucket.Sort(CompareByAreaThenDisplayName);
@@ -147,6 +149,109 @@ public sealed class GalaxyHierarchyIndex
viewsByContainedPath);
}
/// <summary>
/// Re-roots objects that are not reachable from key 0 — members of a multi-node parent
/// cycle (A→B→C→A, every parent present) and anything hanging off one — so they do not
/// vanish from browse. Each cycle is broken at its lowest gobject id.
/// </summary>
private static void ReRootUnreachable(
List<GalaxyObjectView> views,
Dictionary<int, List<GalaxyObjectView>> childrenByParent)
{
HashSet<int> reached = [];
MarkReachable(0, childrenByParent, reached);
if (reached.Count >= views.Count)
{
return;
}
// Ascending id: a cycle member with the lowest id is re-rooted before any other
// member; a descendant hanging off a cycle is reached once its cycle is re-rooted.
foreach (GalaxyObjectView view in views.OrderBy(v => v.Object.GobjectId))
{
int id = view.Object.GobjectId;
if (reached.Contains(id))
{
continue;
}
// Only break at a node that is itself on a cycle (walking parents returns to it);
// a plain descendant of a cycle waits for its ancestor cycle to be broken.
if (!IsOnCycle(view, childrenByParent))
{
continue;
}
childrenByParent[view.Object.ParentGobjectId].Remove(view);
if (!childrenByParent.TryGetValue(0, out List<GalaxyObjectView>? roots))
{
roots = [];
childrenByParent[0] = roots;
}
roots.Add(view);
MarkReachable(0, childrenByParent, reached);
}
}
private static bool IsOnCycle(
GalaxyObjectView start,
Dictionary<int, List<GalaxyObjectView>> childrenByParent)
{
// Descend from start through children; on a cycle we come back to start.
HashSet<int> seen = [];
Stack<int> stack = new();
stack.Push(start.Object.GobjectId);
while (stack.Count > 0)
{
int key = stack.Pop();
if (!childrenByParent.TryGetValue(key, out List<GalaxyObjectView>? kids))
{
continue;
}
foreach (GalaxyObjectView kid in kids)
{
int kidId = kid.Object.GobjectId;
if (kidId == start.Object.GobjectId)
{
return true;
}
if (seen.Add(kidId))
{
stack.Push(kidId);
}
}
}
return false;
}
private static void MarkReachable(
int rootKey,
Dictionary<int, List<GalaxyObjectView>> childrenByParent,
HashSet<int> reached)
{
Stack<int> stack = new();
stack.Push(rootKey);
while (stack.Count > 0)
{
if (!childrenByParent.TryGetValue(stack.Pop(), out List<GalaxyObjectView>? kids))
{
continue;
}
foreach (GalaxyObjectView kid in kids)
{
if (reached.Add(kid.Object.GobjectId))
{
stack.Push(kid.Object.GobjectId);
}
}
}
}
private static string BuildContainedPath(
GalaxyObject obj,
IReadOnlyDictionary<int, GalaxyObject> objectsById)
@@ -1,4 +1,3 @@
using System.Collections.Concurrent;
using System.Runtime.CompilerServices;
using System.Security.Cryptography;
using System.Text;
@@ -23,9 +22,15 @@ public static class GalaxyHierarchyProjector
/// With it, the first page builds the filtered list and each subsequent page is an
/// O(pageSize) slice. The table is keyed on the immutable cache-entry instance, so
/// when the cache publishes a new entry the stale memo becomes unreachable and is
/// reclaimed with it — no explicit invalidation needed.
/// reclaimed with it — no explicit invalidation needed. Each entry's memo is capped at
/// <see cref="ProjectionMemo{TValue}.Capacity"/> signatures, because the signature is
/// client-controlled (GalaxyRepository-001).
/// </summary>
private static readonly ConditionalWeakTable<GalaxyHierarchyCacheEntry, ConcurrentDictionary<string, IReadOnlyList<GalaxyObjectView>>> FilteredViewCache = new();
private static readonly ConditionalWeakTable<GalaxyHierarchyCacheEntry, ProjectionMemo<FilteredViews>> FilteredViewCache = new();
/// <summary>Number of filter signatures currently memoized for <paramref name="entry"/> (tests).</summary>
internal static int MemoCount(GalaxyHierarchyCacheEntry entry) =>
FilteredViewCache.TryGetValue(entry, out var memo) ? memo.Count : 0;
/// <summary>Projects a discovery request against a cache entry and returns all matching objects.</summary>
/// <param name="entry">The Galaxy hierarchy cache entry.</param>
@@ -78,28 +83,33 @@ public static class GalaxyHierarchyProjector
}
string filterSignature = ComputeFilterSignature(request, browseSubtreeGlobs);
IReadOnlyList<GalaxyObjectView> matchedViews = GetFilteredViews(
FilteredViews filtered = GetFilteredViews(
entry,
request,
browseSubtreeGlobs,
maxDepth,
filterSignature);
IReadOnlyList<GalaxyObjectView> matchedViews = filtered.Views;
bool includeAttributes = IncludeAttributes(request);
List<GalaxyObject> page = new(Math.Min(pageSize, Math.Max(0, matchedViews.Count - offset)));
int end = (int)Math.Min((long)offset + pageSize, matchedViews.Count);
for (int index = offset; index < end; index++)
{
page.Add(CloneObject(matchedViews[index].Object, includeAttributes));
// Navigation-only scope ancestors never carry attributes (GalaxyRepository-002).
page.Add(CloneObject(matchedViews[index].Object, includeAttributes && !filtered.NavigationOnly[index]));
}
return new GalaxyHierarchyQueryResult(
page,
matchedViews.Count,
filterSignature);
filterSignature)
{
NavigationAncestorCount = filtered.NavigationAncestorCount,
};
}
private static IReadOnlyList<GalaxyObjectView> GetFilteredViews(
private static FilteredViews GetFilteredViews(
GalaxyHierarchyCacheEntry entry,
DiscoverHierarchyRequest request,
IReadOnlyList<string>? browseSubtreeGlobs,
@@ -111,29 +121,86 @@ public static class GalaxyHierarchyProjector
IReadOnlyList<GalaxyObjectView> views = entry.Index.ObjectViews;
GalaxyObjectView? root = ResolveRoot(request, entry.Index);
ConcurrentDictionary<string, IReadOnlyList<GalaxyObjectView>> memo =
FilteredViewCache.GetValue(entry, static _ => new ConcurrentDictionary<string, IReadOnlyList<GalaxyObjectView>>(StringComparer.Ordinal));
ProjectionMemo<FilteredViews> memo =
FilteredViewCache.GetValue(entry, static _ => new ProjectionMemo<FilteredViews>());
return memo.GetOrAdd(
filterSignature,
static (_, state) =>
{
List<GalaxyObjectView> matched = [];
HashSet<int> inScope = [];
foreach (GalaxyObjectView view in state.Views)
{
if (MatchesRoot(view, state.Root, state.MaxDepth)
&& MatchesBrowseSubtrees(view, state.BrowseSubtreeGlobs)
&& MatchesFilters(view.Object, state.Request))
{
matched.Add(view);
inScope.Add(view.Object.GobjectId);
}
}
return matched;
// A scope such as `Plant/LineA/*` excludes `Plant` and `Plant/LineA` themselves,
// leaving the allowed objects with no parent in the reply (GalaxyRepository-002).
// Ancestors of an allowed object are returned as navigation-only nodes —
// attribute-stripped — when the request would otherwise have returned them
// (inside root/depth, passing the request filters).
HashSet<int> ancestors = state.BrowseSubtreeGlobs is { Count: > 0 }
? CollectAncestors(inScope, state.Index)
: [];
List<GalaxyObjectView> matched = [];
List<bool> navigationOnly = [];
int navigationCount = 0;
foreach (GalaxyObjectView view in state.Views)
{
int id = view.Object.GobjectId;
if (inScope.Contains(id))
{
matched.Add(view);
navigationOnly.Add(false);
}
else if (ancestors.Contains(id)
&& MatchesRoot(view, state.Root, state.MaxDepth)
&& MatchesFilters(view.Object, state.Request))
{
matched.Add(view);
navigationOnly.Add(true);
navigationCount++;
}
}
return new FilteredViews(matched, navigationOnly, navigationCount);
},
(Views: views, Root: root, MaxDepth: maxDepth, BrowseSubtreeGlobs: browseSubtreeGlobs, Request: request));
(Views: views, Index: entry.Index, Root: root, MaxDepth: maxDepth, BrowseSubtreeGlobs: browseSubtreeGlobs, Request: request));
}
/// <summary>
/// The out-of-scope ancestors of every in-scope object. Cycle-safe: a walk stops at any id
/// already seen, which also stops it re-walking a chain another object already covered.
/// </summary>
private static HashSet<int> CollectAncestors(HashSet<int> inScope, GalaxyHierarchyIndex index)
{
HashSet<int> ancestors = [];
foreach (int id in inScope)
{
int parentId = index.ObjectViewsById.TryGetValue(id, out GalaxyObjectView? view) ? view.Object.ParentGobjectId : 0;
while (parentId != 0
&& !inScope.Contains(parentId)
&& ancestors.Add(parentId)
&& index.ObjectViewsById.TryGetValue(parentId, out GalaxyObjectView? parent))
{
parentId = parent.Object.ParentGobjectId;
}
}
return ancestors;
}
private sealed record FilteredViews(
IReadOnlyList<GalaxyObjectView> Views,
IReadOnlyList<bool> NavigationOnly,
int NavigationAncestorCount);
/// <summary>Finds an object in the hierarchy by its tag address.</summary>
/// <param name="entry">The Galaxy hierarchy cache entry.</param>
/// <param name="tagAddress">The tag address to search for.</param>
@@ -13,4 +13,12 @@ namespace ZB.MOM.WW.GalaxyRepository;
public sealed record GalaxyHierarchyQueryResult(
IReadOnlyList<GalaxyObject> Objects,
int TotalObjectCount,
string FilterSignature);
string FilterSignature)
{
/// <summary>
/// How many of the <see cref="TotalObjectCount"/> objects are navigation-only ancestors
/// of a browse-subtree scope: returned (attribute-stripped) only so a client can attach the
/// allowed objects to a tree, not because they are themselves in scope. Always 0 unscoped.
/// </summary>
public int NavigationAncestorCount { get; init; }
}
@@ -46,6 +46,13 @@ public sealed class GalaxyHierarchySnapshotStore : IGalaxyHierarchySnapshotStore
: null;
_writeTimeout = TimeSpan.FromSeconds(Math.Max(1, value.CommandTimeoutSeconds));
_logger = logger;
if (value.PersistSnapshot && _path is null)
{
_logger?.LogInformation(
"Galaxy hierarchy snapshot persistence is disabled: PersistSnapshot is true but SnapshotCachePath is empty. "
+ "Last-known browse data will not survive a restart while the Galaxy database is unreachable.");
}
}
/// <inheritdoc />
@@ -48,8 +48,9 @@ public sealed class GalaxyRepositoryOptions
/// File path for the persisted Galaxy browse snapshot. Ignored when
/// <see cref="PersistSnapshot"/> is <see langword="false"/>. There is no built-in
/// default path — the consumer supplies a cross-platform-friendly path appropriate to
/// its host. When left empty and <see cref="PersistSnapshot"/> is enabled, the
/// snapshot store (a later task) decides where to write.
/// its host. When left empty, snapshot persistence is <b>disabled</b> even if
/// <see cref="PersistSnapshot"/> is <see langword="true"/> (the store logs this once at
/// Information), so the cold-start last-known-data guarantee does not apply.
/// </summary>
public string SnapshotCachePath { get; init; } = string.Empty;
}
@@ -246,7 +246,9 @@ public sealed class GalaxyRepositoryGrpcService(
cache.Current,
new DiscoverHierarchyRequest(),
browseSubtrees);
objectCount = scoped.TotalObjectCount;
// Count the objects the scope allows, not the navigation-only ancestors that the
// projection adds so a tree can be built (GalaxyRepository-002).
objectCount = scoped.TotalObjectCount - scoped.NavigationAncestorCount;
attributeCount = scoped.Objects.Sum(obj => obj.Attributes.Count);
}
@@ -8,6 +8,23 @@ namespace ZB.MOM.WW.GalaxyRepository.Grpc;
/// identity without the library knowing the host's authorization model. The default
/// <see cref="NullGalaxyBrowseScopeProvider"/> applies no scoping (full hierarchy).
/// </summary>
/// <remarks>
/// <para>
/// Each glob is matched (anchored, case-insensitive, <c>*</c>/<c>?</c>) against an
/// object's slash-separated contained path. An object whose path matches any glob is
/// <b>allowed</b> and is returned in full.
/// </para>
/// <para>
/// <b>Ancestors of an allowed object are navigation-only.</b> With <c>Plant/LineA/*</c>,
/// neither <c>Plant</c> nor <c>Plant/LineA</c> matches, but both are returned so a client
/// can reach the allowed subtree: by <c>BrowseChildren</c> (with
/// <c>child_has_children = true</c>) and by <c>DiscoverHierarchy</c>. They are returned
/// with their attributes stripped, and only their children on the path to an allowed
/// object are listed — siblings such as <c>Plant/LineB</c> stay hidden. An ancestor is
/// surfaced only when an allowed descendant also passes the request's own filters.
/// <c>WatchDeployEvents</c> counts allowed objects only.
/// </para>
/// </remarks>
public interface IGalaxyBrowseScopeProvider
{
/// <summary>
@@ -0,0 +1,74 @@
namespace ZB.MOM.WW.GalaxyRepository;
/// <summary>
/// A small, bounded, thread-safe memo of filter-signature → projected result, held per
/// immutable <see cref="GalaxyHierarchyCacheEntry"/>.
/// </summary>
/// <remarks>
/// Bounded because the signature is client-controlled: <c>tag_name_glob</c> values such as
/// <c>*</c>, <c>**</c>, <c>***</c> are all distinct signatures that each retain a full result
/// list, and the per-entry memo is otherwise released only when a new Galaxy deploy publishes
/// a new entry (GalaxyRepository-001). Eviction is FIFO: the memo exists to make paging through
/// ONE filter O(pageSize), and an evicted signature is simply recomputed — the projection is a
/// pure function of the entry and the request, so the answer and its page tokens are unchanged.
/// The factory runs outside the lock; two racing first callers may both compute, and the first
/// to publish wins (same contract as <c>ConcurrentDictionary.GetOrAdd</c>).
/// </remarks>
/// <typeparam name="TValue">The memoized projection.</typeparam>
internal sealed class ProjectionMemo<TValue>
where TValue : class
{
/// <summary>Maximum number of distinct filter signatures retained per cache entry.</summary>
public const int Capacity = 64;
private readonly object _gate = new();
private readonly Dictionary<string, TValue> _items = new(StringComparer.Ordinal);
private readonly Queue<string> _insertionOrder = new();
/// <summary>Number of signatures currently retained.</summary>
public int Count
{
get
{
lock (_gate)
{
return _items.Count;
}
}
}
/// <summary>Returns the memoized value for <paramref name="key"/>, computing it when absent.</summary>
/// <typeparam name="TState">State passed to <paramref name="factory"/>.</typeparam>
/// <param name="key">The filter signature.</param>
/// <param name="factory">Computes the value; must be pure.</param>
/// <param name="state">State for <paramref name="factory"/>.</param>
public TValue GetOrAdd<TState>(string key, Func<string, TState, TValue> factory, TState state)
{
lock (_gate)
{
if (_items.TryGetValue(key, out TValue? existing))
{
return existing;
}
}
TValue created = factory(key, state);
lock (_gate)
{
if (_items.TryGetValue(key, out TValue? raced))
{
return raced;
}
_items[key] = created;
_insertionOrder.Enqueue(key);
while (_items.Count > Capacity)
{
_items.Remove(_insertionOrder.Dequeue());
}
return created;
}
}
}
@@ -6,12 +6,14 @@
<Authors>ZB.MOM.WW</Authors>
<Description>Read-only Galaxy object-hierarchy browse library for the ZB.MOM.WW SCADA family. Provides a SQL provider for the Galaxy Repository database and a canonical gRPC service for exposing the hierarchy to modern .NET 10 clients — extracted from MxAccessGateway so any consumer can browse the Galaxy without loading 32-bit COM.</Description>
<PackageTags>galaxy;repository;browse;aveva;wonderware;system-platform;scada;grpc;sql;zb-mom-ww</PackageTags>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-galaxyrepository</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-galaxyrepository</RepositoryUrl>
<PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/scadaproj/src/branch/main/ZB.MOM.WW.GalaxyRepository</PackageProjectUrl>
<RepositoryUrl>https://gitea.dohertylan.com/dohertj2/scadaproj</RepositoryUrl>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Data.SqlClient" />
<!-- Direct reference so the centrally pinned, patched version flows to consumers (GalaxyRepository-007). -->
<PackageReference Include="System.Security.Cryptography.Pkcs" />
<PackageReference Include="Grpc.AspNetCore" />
<PackageReference Include="Google.Protobuf" />
<PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" />
@@ -22,7 +24,6 @@
</PackageReference>
</ItemGroup>
<!-- Proto files are added in Task 2; the empty glob is intentional and builds cleanly. -->
<ItemGroup>
<Protobuf Include="Protos\*.proto" GrpcServices="Server" />
</ItemGroup>

Some files were not shown because too many files have changed in this diff Show More