Initial design docs from claude.ai refinement sessions

Component-Security.md

@@ -0,0 +1,96 @@
+# Component: Security & Auth
+
+## Purpose
+
+The Security & Auth component handles user authentication via LDAP/Active Directory and enforces role-based authorization across the system. It maps LDAP group memberships to system roles and applies permission checks to all operations.
+
+## Location
+
+Central cluster. Sites do not have user-facing interfaces and do not perform independent authentication.
+
+## Responsibilities
+
+- Authenticate users against LDAP/Active Directory using Windows Integrated Authentication.
+- Map LDAP group memberships to system roles.
+- Enforce role-based access control on all API and UI operations.
+- Support site-scoped permissions for the Deployment role.
+
+## Authentication
+
+- **Mechanism**: Windows Integrated Authentication (Kerberos/NTLM) against Active Directory.
+- **Session**: Authenticated user identity is maintained for the duration of the UI session.
+- **No local user store**: All identity and group information comes from AD.
+
+## Roles
+
+### Admin
+- **Scope**: System-wide (always).
+- **Permissions**:
+  - Manage site definitions.
+  - Manage site-level data connections (define and assign to sites).
+  - Manage area definitions per site.
+  - Manage LDAP group-to-role mappings.
+  - Manage API keys (create, enable/disable, delete).
+  - System-level configuration.
+  - View audit logs.
+
+### Design
+- **Scope**: System-wide (always).
+- **Permissions**:
+  - Create, edit, delete templates (including attributes, alarms, scripts).
+  - Manage shared scripts.
+  - Manage external system definitions.
+  - Manage database connection definitions.
+  - Manage notification lists and SMTP configuration.
+  - Manage inbound API method definitions.
+  - Run on-demand validation (template flattening, script compilation).
+
+### Deployment
+- **Scope**: System-wide or site-scoped.
+- **Permissions**:
+  - Create and manage instances (overrides, connection bindings, area assignment).
+  - Disable, enable, and delete instances.
+  - Deploy configurations to instances.
+  - Deploy system-wide artifacts (shared scripts, external system definitions, DB connections, notification lists) to all sites.
+  - View deployment diffs and status.
+  - Use debug view.
+  - Manage parked messages.
+  - View site event logs.
+- **Site scoping**: A user with site-scoped Deployment role can only perform these actions for instances at their permitted sites.
+
+## Multi-Role Support
+
+- A user can hold **multiple roles simultaneously** by being a member of multiple LDAP groups.
+- Roles are **independent** — there is no implied hierarchy between roles.
+- For example, a user who is a member of both `SCADA-Designers` and `SCADA-Deploy-All` holds both the Design and Deployment roles, allowing them to author templates and also deploy configurations.
+
+## LDAP Group Mapping
+
+- System administrators configure mappings between LDAP groups and roles.
+- Examples:
+  - `SCADA-Admins` → Admin role
+  - `SCADA-Designers` → Design role
+  - `SCADA-Deploy-All` → Deployment role (all sites)
+  - `SCADA-Deploy-SiteA` → Deployment role (Site A only)
+  - `SCADA-Deploy-SiteB` → Deployment role (Site B only)
+- A user can be a member of multiple groups, granting multiple independent roles.
+- Group mappings are stored in the configuration database and managed via the Central UI (Admin role).
+
+## Permission Enforcement
+
+- Every API endpoint and UI action checks the authenticated user's roles before proceeding.
+- Site-scoped checks additionally verify the target site is within the user's permitted sites.
+- Unauthorized actions return an appropriate error and are not logged as audit events (only successful changes are audited).
+
+## Dependencies
+
+- **Active Directory / LDAP**: Source of user identity and group memberships.
+- **Configuration Database (MS SQL)**: Stores LDAP group-to-role mappings and site scoping rules.
+- **Configuration Database (via IAuditService)**: Security/admin changes (role mapping updates) are audit logged.
+
+## Interactions
+
+- **Central UI**: All UI requests pass through authentication and authorization.
+- **Template Engine**: Design role enforcement.
+- **Deployment Manager**: Deployment role enforcement with site scoping.
+- **All central components**: Role checks are a cross-cutting concern applied at the API layer.