From f624217af8599254d3aec25599ca0802431de71e Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Mon, 1 Jun 2026 04:12:43 -0400 Subject: [PATCH] docs: add human-facing repo README Complements CLAUDE.md (the Claude-Code index) with a human overview: what's in here, the sister projects + data flow, the component- normalization concept, and the ZB.MOM.WW.Auth package/consumer matrix with build/test commands. --- README.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e721f5d --- /dev/null +++ b/README.md @@ -0,0 +1,101 @@ +# scadaproj + +Umbrella workspace for a family of related **SCADA / OT** (operational-technology) projects +built around **AVEVA System Platform (Wonderware)**, **OPC UA**, and **Akka.NET**. + +This repository is part **index** — a map of the sister projects, which are their own +repositories — and part **home** for cross-project *normalization* work and the shared code +it produces. + +> Working in here with Claude Code? See [`CLAUDE.md`](CLAUDE.md) for the machine-oriented +> index and guidance. This README is the human-facing overview. + +## What's in here + +| 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 | +| [`docs/plans/`](docs/plans/) | Implementation plans (e.g. the ZB.MOM.WW.Auth build) | +| [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/) | **Built shared library** (.NET 10) — the realized output of the auth normalization | + +## The sister projects + +Independent repositories, coupled only at **runtime over wire protocols** (gRPC + OPC UA) — +not by a shared build. scadaproj *indexes* them; it does not contain them. + +- **OtOpcUa** (`lmxopcua`) — OPC UA server (.NET 10) that republishes Wonderware Galaxy tags as + an OPC UA address space. +- **MxAccessGateway** (`mxaccessgw`) — gRPC gateway giving modern x64 / .NET-10 clients full + 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. + +Data flow: + +``` +Wonderware Galaxy ──gRPC──▶ mxaccessgw ──▶ OtOpcUa (republishes as OPC UA) ─┐ + └────────────────────────────────────┴─▶ ScadaBridge clusters + (or ScadaBridge's MxGateway adapter, direct) +``` + +Full relationship map: [`CLAUDE.md`](CLAUDE.md#cross-project-relationships). + +## Component normalization + +The sister repos kept re-implementing the same cross-cutting concerns and drifting apart. +[`components/`](components/) captures, per component, the **one target** spec, each project's +**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/) | + +## `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)). + +| Package | Purpose | Used by | +|---|---|---| +| `ZB.MOM.WW.Auth.Abstractions` | Contracts, `CanonicalRole`, API-key types (zero deps) | all | +| `ZB.MOM.WW.Auth.Ldap` | Bind-then-search LDAP authentication (fail-closed) | all | +| `ZB.MOM.WW.Auth.ApiKeys` | Peppered-HMAC API keys + SQLite store + verifier + admin commands | MxAccessGateway, ScadaBridge | +| `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. + +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 +it onto the canonical roles. Design: [`components/auth/spec/SPEC.md`](components/auth/spec/SPEC.md) +and [`CANONICAL-ROLES.md`](components/auth/spec/CANONICAL-ROLES.md). + +### Build & test + +```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 +``` + +Stack: .NET 10 · xUnit · `Novell.Directory.Ldap.NETStandard` · `Microsoft.Data.Sqlite` · central +package management. The packages are **libraries linked into each consumer** — there is **no +central auth service**. More detail: [`ZB.MOM.WW.Auth/README.md`](ZB.MOM.WW.Auth/README.md). + +The optional LDAP integration test is opt-in: + +```bash +ZB_LDAP_IT=1 dotnet test # requires a reachable GLAuth (e.g. a sister repo's infra/glauth) +``` + +## 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). +- ⬜ Normalize the next cross-cutting component.