wip: doctor/cli/docs/api to vector db consolidation; api hardening for descriptions, tenant, and scopes; migrations and conversions of all DALs to EF v10

2026-02-23 15:30:50 +02:00
parent bd8fee6ed8
commit e746577380
1424 changed files with 81225 additions and 25251 deletions
--- a/docs/technical/architecture/console-admin-rbac.md
+++ b/docs/technical/architecture/console-admin-rbac.md
@@ -4,6 +4,7 @@
 - Provide a unified, Authority-backed admin surface for tenants, users, roles, clients, tokens, and audit.
 - Expose the same capabilities to UI and CLI while preserving offline-first operation.
 - Normalize scope and role bundles, including missing Scanner roles, for consistent RBAC across modules.
+- Align tenant assignment and selection behavior with `docs/architecture/decisions/ADR-002-multi-tenant-same-api-key-selection.md`.

 ## 2. Scope
 - Authority admin APIs and data model used by the Console Admin workspace.
@@ -234,3 +235,7 @@ Scopes: `authority:tokens.read|revoke`, `authority:audit.read`
 - `docs/modules/ui/architecture.md`
 - `docs/UI_GUIDE.md`
 - `docs/contracts/web-gateway-tenant-rbac.md`
+- `docs/technical/architecture/multi-tenant-service-impact-ledger.md`
+- `docs/technical/architecture/multi-tenant-flow-sequences.md`
+- `docs/operations/multi-tenant-rollout-and-compatibility.md`
+- `docs/qa/feature-checks/multi-tenant-acceptance-matrix.md`
--- a/docs/technical/architecture/multi-tenant-flow-sequences.md
+++ b/docs/technical/architecture/multi-tenant-flow-sequences.md
@@ -0,0 +1,106 @@
+# Multi-Tenant Same-Key End-to-End Flow Sequences
+
+Date: 2026-02-22  
+Source sprint: `SPRINT_20260222_053_DOCS_multi_tenant_same_api_key_contract_baseline.md`  
+Related ADR: `docs/architecture/decisions/ADR-002-multi-tenant-same-api-key-selection.md`
+
+## 1) Sign-in to Tenant Mapping
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant User
+    participant Web as Web Console
+    participant Auth as Authority
+    participant Gw as Router/Gateway
+    participant Svc as Tenant-scoped API
+
+    User->>Web: Sign in
+    Web->>Auth: /connect/authorize + PKCE
+    Auth-->>Web: auth code
+    Web->>Auth: /connect/token (client credentials or password grant, tenant=<optional>)
+    Auth->>Auth: Resolve selected tenant from tenant + tenants metadata
+    Auth-->>Web: Access token (stellaops:tenant + optional stellaops:allowed_tenants)
+    Web->>Auth: /console/tenants
+    Auth-->>Web: { tenants[], selectedTenant }
+    Web->>Web: Hydrate ConsoleSessionStore + AuthSessionStore + PlatformContext
+    Web->>Gw: API request + canonical tenant header
+    Gw->>Svc: Forward resolved tenant context
+    Svc-->>Web: Tenant-scoped response
+```
+
+Deterministic selection rule:
+- If `tenant` parameter is present at token request time, it must be in assigned tenant set.
+- If no parameter and only one assignment/default exists, use that selected tenant.
+- If ambiguous (multi-assigned and no default/request), reject.
+
+## 2) Header Selector Tenant Switch
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant User
+    participant Topbar as Header Tenant Selector
+    participant Session as ConsoleSessionService
+    participant Auth as Authority
+    participant Stores as Session/Context Stores
+    participant APIs as Platform/Scanner/Graph APIs
+
+    User->>Topbar: Select tenant "tenant-bravo"
+    Topbar->>Session: switchTenant("tenant-bravo")
+    Session->>Stores: Optimistic selectedTenant update
+    Session->>Auth: /console/tenants (tenant header=tenant-bravo)
+    Auth-->>Session: allowed tenants + selectedTenant
+    Session->>Auth: /console/profile + /console/token/introspect
+    Auth-->>Session: profile/token introspection for selected tenant
+    Session->>Stores: Commit tenant to Console/Auth/Platform/TenantActivation stores
+    Session->>APIs: Trigger context reload for tenant-scoped data
+    APIs-->>Topbar: Refreshed tenant-scoped responses
+```
+
+Error recovery path:
+- On switch failure (`403`, `tenant_conflict`, session expiry), restore previous tenant in all stores.
+- Attempt context reload for previous tenant.
+- Surface deterministic error in tenant panel with retry action.
+
+## 3) API Request Propagation Through Gateway
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Web API Client
+    participant I as Tenant/Context Interceptors
+    participant Gw as Router/Gateway
+    participant Backend as Platform/Scanner/Graph
+
+    UI->>I: Outgoing request
+    I->>I: Resolve active tenant from canonical runtime state
+    I-->>UI: Add canonical header X-StellaOps-Tenant (+ compat aliases)
+    UI->>Gw: Request with tenant headers + token
+    Gw->>Gw: Strip caller-supplied identity headers, derive tenant from validated claims, rewrite canonical headers
+    Gw->>Backend: Forward tenant-scoped request
+    Backend->>Backend: Resolve tenant context + enforce tenant ownership
+    Backend-->>UI: Deterministic success/failure payload
+```
+
+Cache/store invalidation points after tenant switch:
+- Console session context cache.
+- Tenant-scoped page stores (Platform/Scanner/Graph read models).
+- URL context synchronization where tenant is persisted as global context.
+
+## 4) Failure Sequences
+
+### Missing tenant context
+- Expected result: deterministic `400`/`401`/`403` based on service policy and auth stage.
+- UI behavior: keep prior selection if available; show recoverable error panel.
+
+### Tenant mismatch
+- Trigger: claim tenant != header/request tenant.
+- Expected result: reject with deterministic conflict error (for example `tenant_conflict` or `tenant_forbidden`).
+- Audit/telemetry: record attempted tenant override + resolved tenant.
+
+### Insufficient scope
+- Trigger: token lacks required policy scope for requested endpoint.
+- Expected result: deterministic `403` with scope policy failure context.
+- UI behavior: no tenant mutation; show access-denied state.
+
--- a/docs/technical/architecture/multi-tenant-service-impact-ledger.md
+++ b/docs/technical/architecture/multi-tenant-service-impact-ledger.md
@@ -0,0 +1,35 @@
+# Multi-Tenant Same-Key Service Impact Ledger
+
+Date: 2026-02-22  
+Source sprint: `SPRINT_20260222_053_DOCS_multi_tenant_same_api_key_contract_baseline.md`  
+Related ADR: `docs/architecture/decisions/ADR-002-multi-tenant-same-api-key-selection.md`
+
+## Purpose
+- Provide a single implementation ledger for services affected by same-key multi-tenant selection.
+- Prevent contract drift across Authority, Router/Gateway, Platform, Scanner, Graph, and Web.
+
+## Change Ledger
+
+| Service | Sprint | File-level touchpoint categories | Owner role | Depends on | Verification evidence |
+| --- | --- | --- | --- | --- | --- |
+| Authority | `20260222.054` | `Console/Admin endpoints`, `OpenIddict handlers`, `Client metadata stores`, `Auth abstractions`, `Authority tests` | Developer + Test Automation | ADR-002 | Targeted Authority test project pass logs for client credentials/password grant tenant selection, token validation mismatch, `/console/tenants`, and admin client CRUD tenant assignments. |
+| Router + Gateway | `20260222.055` | `Identity header policy middleware`, `tenant override gating`, `route passthrough policy`, `middleware parity tests` | Developer + Security architect | `20260222.054` | Targeted Router and Gateway tests proving spoof stripping, no authenticated default fallback, mismatch rejection, and feature-flagged override behavior. |
+| Platform | `20260222.056` | `Request context resolver`, `tenant-required endpoint groups`, `topology/read-model store callers`, `context preferences`, `platform integration tests` | Developer + Test Automation | `20260222.055` | Platform test project outputs validating endpoint classification, tenant parity checks, topology isolation, and tenant-scoped preference behavior. |
+| Scanner | `20260222.057` | `Scanner request resolver`, `scan submission/coordinator`, `triage query contracts`, `webhook tenant lookup`, `unknowns endpoints`, `scanner tests` | Developer + Test Automation | `20260222.055` | Scanner tenant isolation test outputs for scan ownership, triage isolation, webhook source collision routing, unknowns isolation, and middleware partitioning. |
+| Graph | `20260222.058` | `Graph request resolver`, `endpoint auth policies`, `scope handling`, `rate-limit/audit tenant keys`, `graph API tests` | Developer + Test Automation | `20260222.055` | Graph API test outputs covering missing tenant, cross-tenant denial, missing-scope denial, and export ownership checks. |
+| Web Console | `20260222.059` | `Topbar tenant selector`, `console/auth/platform context stores`, `tenant interceptor`, `authority console client`, `component/unit tests` | Developer + Test Automation | `20260222.054`, `20260222.055` | Web unit/component test outputs for selector UX, state synchronization, interceptor canonical+legacy headers, switch rollback, and URL context sync. |
+| QA / Playwright matrix | `20260222.060` | `Playwright fixtures`, `tenant-switch specs`, `Tier 2a API verification docs`, `Tier 2c artifact bundle` | QA + Test Automation | `20260222.054`..`20260222.059` | Playwright run output, traces/screenshots, and module-level API isolation evidence with explicit go/no-go decision. |
+
+## Ownership and Dependency Notes
+- Authority is the contract anchor for selected-tenant-per-token issuance and assignment validation.
+- Router/Gateway establishes canonical header rewrite and anti-spoofing behavior for downstream services.
+- Platform, Scanner, and Graph must consume resolved tenant context and reject cross-tenant mismatches deterministically.
+- Web must maintain one runtime tenant source of truth and propagate it through canonical interceptor paths.
+
+## Completion Mapping
+- `DOC-TEN-03` completion is satisfied when each ledger row has:
+  - explicit touchpoint categories,
+  - clear owner role,
+  - dependency reference,
+  - verification evidence definition.
+