Joseph Doherty
3dd7aa40ff
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
6.7 KiB
Auth — gaps & adoption backlog
Divergence of each project from spec/SPEC.md, and the ordered backlog to
reach the shared ZB.MOM.WW.Auth library. Status legend: ⛔ gap · 🟡 partial · ✅ matches.
Current state (verified 2026-07-18): feed carries
0.1.0–0.1.4; consumer pins are OtOpcUa0.1.1, ScadaBridge0.1.3, MxAccessGateway0.1.4, HistorianGateway0.1.4(a fourth consumer this file predates, taking all four packages). OtOpcUa is three minors behind — it does not get the0.1.4API-key-expiry enforcement. Library suite: 215 passing, 1 skipped, green 2026-07-18.✅ ADOPTED 2026-06-02 (local-only). The full backlog (#1–#8) was implemented across all three apps on each repo's
feat/adopt-zb-authbranch — committed + spec/code-reviewed, then merged to each repo's local default (main/master) and PUSHED to origin (gitea) on 2026-06-03 (in sync;feat/*kept locally). SharedAuth.Ldap+Auth.ApiKeys(ScadaBridge inbound re-architected to keyId/Bearer),IGroupRoleMapper<TRole>,Transport-enum config, canonicalZbClaimTypes/ZbCookieDefaults, unified dev base DNdc=zb,dc=local, and the canonical-six roles (with ScadaBridge's accepted auditor/admin SoD collapse). Consumer pins: OtOpcUa0.1.1, MxGateway0.1.2, ScadaBridge0.1.3. Detail:docs/plans/2026-06-02-auth-audit-normalization*.md. The ⛔/🟡 cells below describe the PRE-adoption divergence (kept for history).
Divergence vs spec
§1 LDAP config schema
| Spec key | OtOpcUa | MxAccessGateway | ScadaBridge |
|---|---|---|---|
| Section nesting | 🟡 Authentication:Ldap (nested) |
✅ MxGateway:Ldap (nested) |
⛔ flat ScadaBridge:Security:Ldap* |
Transport enum |
⛔ UseTls bool |
⛔ UseTls bool |
✅ LdapTransport enum |
AllowInsecure |
🟡 AllowInsecureLdap |
🟡 AllowInsecureLdap |
🟡 AllowInsecureLdap (rename) |
UserNameAttribute |
✅ UserNameAttribute |
✅ UserNameAttribute |
⛔ LdapUserIdAttribute |
GroupAttribute |
✅ memberOf |
✅ memberOf |
🟡 LdapGroupAttribute (rename) |
dev SearchBase |
dc=lmxopcua,dc=local |
dc=lmxopcua,dc=local |
dc=scadabridge,dc=local |
→ Gap A1: adopt the Transport enum in OtOpcUa + gateway (replace UseTls).
→ Gap A2: ScadaBridge: nest keys + rename LdapUserIdAttribute→UserNameAttribute, LdapGroupAttribute→GroupAttribute.
→ Gap A3: unify the dev base DN (dc=lmxopcua vs dc=scadabridge) — pick one shared GLAuth base.
§2 bind-then-search
All three do bind-then-search; ScadaBridge has the most complete hygiene (RFC-4514 + filter escaping, per-op timeout, fail-closed on group lookup, username trim, service-account-bind distinction). 🟡 OtOpcUa/gateway: confirm each has filter escaping + fail-closed-on-group-lookup parity. → Gap B1: make ScadaBridge's hygiene the shared baseline; backfill any missing checks.
§3 group→role mapping
⛔ Mechanism split: OtOpcUa + gateway map in config (GroupToRole); ScadaBridge maps in
the database (LdapGroupMapping). → Gap C1: IGroupRoleMapper<CanonicalRole> must support both
backings; ship a config-backed and a DB/delegate-backed mapper.
⛔ Role vocabulary now standardized to the canonical six (spec/CANONICAL-ROLES.md);
native enforcement stays per-project. → Gap C2: implement the canonical → native expansion in each
project. ⚠ Removing Auditor collapses ScadaBridge AuditReadOnly→Viewer and Audit→Administrator,
losing its auditor/admin separation-of-duties (accepted). OtOpcUa lacks a first-class Deployer
(publish ⊂ FleetAdmin); ScadaBridge has no Operator/Engineer; mxaccessgw no Designer/Deployer —
each project assigns only the applicable subset.
§4 API-key contract
| OtOpcUa | MxAccessGateway | ScadaBridge | |
|---|---|---|---|
| Has API keys | n/a (OPC UA transport security) | ✅ mxgw_…, SQLite, scopes + constraints |
🟡 X-API-Key, per-method approval (Inbound API only) |
| Peppered HMAC-SHA256 | — | ✅ | ✅ |
| Constant-time compare | — | ✅ | ✅ |
Token format <prefix>_<id>_<secret> |
— | ✅ | ⛔ raw X-API-Key (no keyId/prefix structure) |
| Audit log | — | ✅ append-only | 🟡 (verify) |
→ Gap D1: extract mxaccessgw's pipeline as ZB.MOM.WW.Auth.ApiKeys.
→ Gap D2: ScadaBridge Inbound API adopts it; reconcile token format and model "per-method approval" as the opaque constraint policy.
§5 cookie / claim conventions
⛔ Cookie names differ (MxGatewayDashboard vs ZB.MOM.WW.ScadaBridge.Auth vs OtOpcUa control-plane cookie); claim-type conventions differ. → Gap E1: define canonical claim types + cookie defaults in ZB.MOM.WW.Auth.AspNetCore; each app keeps its own cookie name but shares attributes/claims.
§6 dev / secrets
✅ All never-log-secrets and pepper-external. 🟡 escape-hatch flag names vary. Covered by A3 (base DN) + E.
Adoption backlog (ordered)
| # | Item | Projects | Priority | Effort | Risk | Notes |
|---|---|---|---|---|---|---|
| 1 | Extract ZB.MOM.WW.Auth.Ldap from ScadaBridge's hardened impl |
all 3 | High | M | Med | security-sensitive; needs strong tests before cutover |
| 2 | Extract ZB.MOM.WW.Auth.ApiKeys from mxaccessgw Model A |
gw, SB | High | M | Med | gateway adopts first (it's the source), then SB |
| 3 | IGroupRoleMapper<TRole> seam + config & DB mappers (Gap C1) |
all 3 | High | S | Low | unblocks per-project role retention |
| 4 | Config migration to §1 schema (Gaps A1–A2) | all 3 | Med | S | Low | mechanical; do with #1 |
| 5 | ZB.MOM.WW.Auth.AspNetCore claims/cookie conventions (Gap E1) |
all 3 (UIs) | Med | S | Low | incl. OtOpcUa Blazor Admin UI control-plane |
| 6 | Unify dev GLAuth base DN (Gap A3) | all 3 | Low | S | Low | dev-only; touches fixtures/infra |
| 7 | Decide shared JWT/refresh helper vs per-project | SB (+?) | Low | S | Low | only if a 2nd project wants the same |
| 8 | Adopt canonical roles: canonical → native mapping per project (Gap C2) |
all 3 | Med | M | Med | governance (assign canonical role per LDAP group org-wide) + each project's expansion; SB audit roles collapse |
Sequencing: #3 first (cheap, unblocks), then #1 and #2 in parallel (independent libraries), then #4–#5 alongside cutover, then #6–#7 as cleanup. Each extraction lands behind tests in the source project before any consumer migrates. This stays consistent with the repos' loose coupling: adoption is opt-in per project, one consumer version-bump at a time.
Decisions still open
- Shared dev base DN value (A3).
- Whether constraints stay opaque
object?or get a smallIConstraintPolicy(shared-contract Q3). - Shared JWT/refresh helper or not (#7).