ahmido
110245a9ec
Some checks are pending
Main Confidence / confidence (push) Waiting to run
## Summary - add a shared provider target-scope descriptor, normalizer, identity-context metadata, and surface-summary layer - update provider connection list, detail, create, edit, and onboarding surfaces to use neutral target-scope vocabulary while keeping Microsoft identity contextual - align provider connection audit and resolver output with the neutral target-scope contract and add focused guard/unit/feature coverage for regressions ## Validation - browser smoke: opened the tenant-scoped provider connection list, drilled into detail, and verified the edit/create surfaces in local admin context ## Notes - this PR comes from the session branch created for the active feature work - no additional runtime or persistence layer was introduced in this slice Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #274
140 lines
6.7 KiB
Markdown
140 lines
6.7 KiB
Markdown
# Data Model: Provider Identity & Target Scope Neutrality
|
|
|
|
## Overview
|
|
|
|
This slice introduces one shared target-scope descriptor, one provider-owned contextual identity metadata shape, one operator-facing connection summary, and one narrow neutrality guard result. No new database persistence is introduced.
|
|
|
|
## Entity: ProviderConnectionTargetScopeDescriptor
|
|
|
|
- **Purpose**: Express the neutral platform meaning of what a provider connection points to without carrying provider-specific identity as part of the descriptor itself.
|
|
- **Identity**:
|
|
- `provider_connection_id` for existing records
|
|
- draft or create-flow input tuple `(provider, scope_kind, scope_identifier, scope_display_name)` before persistence
|
|
- **Core fields**:
|
|
- `provider`
|
|
- `scope_kind`
|
|
- `scope_identifier`
|
|
- `scope_display_name`
|
|
- `shared_label`
|
|
- `shared_help_text`
|
|
- **Validation rules**:
|
|
- The descriptor must remain renderable without provider-specific labels.
|
|
- In this current-release slice, `scope_kind` is tenant-only even though the neutral field remains generic for future provider-boundary-safe extension.
|
|
- `scope_kind`, `scope_identifier`, and `scope_display_name` must be sufficient to describe the neutral target-scope meaning on shared surfaces.
|
|
- `scope_identifier` and `scope_display_name` must be usable on shared surfaces without relying on Microsoft directory vocabulary.
|
|
- Provider-owned identity details must live beside the descriptor in contextual metadata or summary shapes, not inside the descriptor itself.
|
|
|
|
## Entity: ProviderConnectionTargetScopeNormalizationResult
|
|
|
|
- **Purpose**: Represent the deterministic result of normalizing create or edit input before persistence, including explicit blocked outcomes for unsupported combinations or missing provider context.
|
|
- **Fields**:
|
|
- `status`
|
|
- `provider`
|
|
- `scope_kind`
|
|
- `target_scope` when `status = normalized`
|
|
- `contextual_identity_details[]` when `status = normalized`
|
|
- `preview_summary` when a shared-surface preview can be derived without assuming persisted runtime state
|
|
- `failure_code`
|
|
- `message`
|
|
- **Status values**:
|
|
- `normalized`
|
|
- `blocked`
|
|
- **Failure code values**:
|
|
- `none`
|
|
- `unsupported_provider_scope_combination`
|
|
- `missing_provider_context`
|
|
- **Validation rules**:
|
|
- `normalized` results must carry `provider`, `scope_kind`, `target_scope`, `contextual_identity_details[]`, `failure_code = none`, and a human-readable `message`; they may include `preview_summary` only when consent and verification state can be derived without assuming persisted runtime state.
|
|
- `blocked` results must carry `provider`, `scope_kind`, `failure_code`, and `message` and must not pretend readiness or persisted summary truth exists.
|
|
- The normalization result must preserve the distinction between neutral target-scope truth and provider-owned contextual identity details.
|
|
|
|
## Entity: ProviderIdentityContextMetadata
|
|
|
|
- **Purpose**: Carry provider-owned identity details that remain necessary for Microsoft consent, verification, troubleshooting, or audit drill-in.
|
|
- **Fields**:
|
|
- `provider`
|
|
- `detail_key`
|
|
- `detail_label`
|
|
- `detail_value`
|
|
- `visibility`
|
|
- **Visibility values**:
|
|
- `contextual_only`
|
|
- `audit_only`
|
|
- `troubleshooting_only`
|
|
- **Validation rules**:
|
|
- Context metadata must never replace the shared target-scope descriptor on generic provider surfaces.
|
|
- Microsoft-only labels such as `Entra tenant ID` remain allowed only when `provider = microsoft` and visibility is contextual.
|
|
|
|
## Entity: ProviderConnectionSurfaceSummary
|
|
|
|
- **Purpose**: Define the default-visible operator-facing summary for shared provider connection surfaces.
|
|
- **Fields**:
|
|
- `provider`
|
|
- `target_scope`
|
|
- `consent_state`
|
|
- `verification_state`
|
|
- `readiness_summary`
|
|
- `contextual_identity_details[]`
|
|
- **Validation rules**:
|
|
- `provider`, `target_scope`, `consent_state`, and `verification_state` must all be visible without opening diagnostics.
|
|
- `contextual_identity_details[]` must remain secondary to the target-scope summary.
|
|
- Shared surface summaries must not collapse consent and verification into one ambiguous state.
|
|
|
|
## Entity: ProviderConnectionNeutralityCheckResult
|
|
|
|
- **Purpose**: Deterministic result shape used by guard tests and review checks.
|
|
- **Fields**:
|
|
- `status`
|
|
- `surface_key`
|
|
- `path`
|
|
- `surface_ownership`
|
|
- `allowed_exception_classes[]`
|
|
- `violation_code`
|
|
- `message`
|
|
- `suggested_follow_up`
|
|
- **Status values**:
|
|
- `allowed`
|
|
- `review_required`
|
|
- `blocked`
|
|
- **Violation code examples**:
|
|
- `provider_specific_default_label`
|
|
- `provider_specific_default_filter`
|
|
- `provider_specific_required_field`
|
|
- `provider_specific_validation_message`
|
|
- `provider_specific_default_helper_copy`
|
|
- `provider_specific_default_audit_prose`
|
|
- `missing_target_scope_descriptor`
|
|
- **Surface ownership values**:
|
|
- `platform_core`
|
|
- `provider_owned`
|
|
- **Validation rules**:
|
|
- `allowed` means the shared surface uses neutral target-scope truth by default.
|
|
- `review_required` means the path contains documented provider-owned contextual detail or an allowed exception class.
|
|
- `blocked` means a shared surface reintroduced provider-specific default truth.
|
|
|
|
## Relationships
|
|
|
|
- One `ProviderConnectionSurfaceSummary` consumes exactly one `ProviderConnectionTargetScopeDescriptor` and may carry zero or more `ProviderIdentityContextMetadata` entries beside it.
|
|
- One `ProviderConnectionTargetScopeNormalizationResult` may carry zero or more `ProviderIdentityContextMetadata` entries beside exactly one normalized target-scope descriptor.
|
|
- One `ProviderConnectionNeutralityCheckResult` references exactly one touched surface or helper path.
|
|
|
|
## Lifecycle
|
|
|
|
### Target-scope descriptor lifecycle
|
|
|
|
- `draft_input`: create or edit flow has neutral shared scope data but is not yet persisted.
|
|
- `persisted_shared_truth`: existing `provider_connections` row has a neutral target-scope descriptor available for shared surfaces.
|
|
- `context_enriched`: provider-owned contextual details are attached for Microsoft consent, verification, or audit drill-in.
|
|
|
|
### Neutrality check lifecycle
|
|
|
|
- `allowed`: shared surface is neutral by default.
|
|
- `review_required`: shared surface stays neutral but exposes documented provider-owned contextual detail.
|
|
- `blocked`: shared surface or helper reintroduced provider-specific default truth.
|
|
|
|
## Rollout Model
|
|
|
|
- No new database table or column is planned for this slice.
|
|
- The descriptor layer is derived from existing provider connection truth and existing provider-owned identity details.
|
|
- Provider connection list, detail, create, edit, onboarding provider setup, and audit wording adopt the new descriptor first.
|
|
- Broader provider identity migration and compare-boundary work remain out of scope for this feature. |