TenantAtlas/specs/137-platform-provider-identity/data-model.md

# Data Model: Platform Provider Identity Standardization

## 1. ProviderConnection

**Purpose**: Tenant-owned record that models the tenant’s Microsoft connection state without storing centrally managed platform secrets.

### Fields

| Field | Type | Required | Notes |
|---|---|---:|---|
| `id` | bigint | yes | Existing primary key |
| `workspace_id` | bigint FK | yes | Existing workspace ownership |
| `tenant_id` | bigint FK | yes | Existing tenant ownership |
| `provider` | string | yes | Existing, remains `microsoft` for this feature scope |
| `entra_tenant_id` | string | yes | Existing target tenant directory ID |
| `display_name` | string | yes | Existing operator-visible label |
| `is_default` | boolean | yes | Existing default invariant per tenant/provider |
| `connection_type` | string | yes | New; `platform` or `dedicated` |
| `status` | string | yes | Existing backward-compatible summary; no longer canonical for consent or verification |
| `consent_status` | string | yes | New; `unknown`, `required`, `granted`, `failed`, `revoked` |
| `consent_granted_at` | timestamp nullable | no | New |
| `consent_last_checked_at` | timestamp nullable | no | New |
| `consent_error_code` | string nullable | no | New; sanitized identity-provider or platform reason code |
| `consent_error_message` | string nullable | no | New; sanitized operator-safe message |
| `verification_status` | string | yes | New; `unknown`, `pending`, `healthy`, `degraded`, `blocked`, `error` |
| `health_status` | string | yes | Existing operational summary retained for compatibility |
| `last_health_check_at` | timestamp nullable | no | Existing |
| `last_error_reason_code` | string nullable | no | Existing, remains runtime-oriented |
| `last_error_message` | string nullable | no | Existing, sanitized |
| `scopes_granted` | jsonb | yes | Existing; may continue to hold observed permission snapshots |
| `metadata` | jsonb | yes | Existing; used for migration-review flags and display-only hints such as effective app metadata |
| `created_at` / `updated_at` | timestamps | yes | Existing |

### Validation Rules

- `provider` must remain within supported provider types and is `microsoft` for this feature.
- `connection_type` must be one of `platform` or `dedicated`.
- `consent_status` must be one of the defined consent states.
- `verification_status` must be one of the defined verification states.
- `workspace_id` and `tenant_id` must match the resolved tenant scope.
- `platform` connections must not require a `ProviderCredential` row.
- `dedicated` connections may not be marked operationally ready without a valid credential row.

### Relationships

- Belongs to one `Tenant`
- Belongs to one `Workspace`
- Has zero or one `ProviderCredential`
- Emits many `AuditLog` entries indirectly via resource or service actions

### State Transitions

#### Standard platform flow

1. Create connection
   - `connection_type=platform`
   - `consent_status=required`
   - `verification_status=unknown`
   - `status=needs_consent`
2. Consent granted
   - `consent_status=granted`
   - `consent_granted_at` set
   - `verification_status` remains `unknown` or moves to `pending` when verification starts
3. Verification succeeds
   - `verification_status=healthy`
   - `health_status=healthy` or existing canonical success value
   - `status=connected`
4. Verification fails after granted consent
   - `consent_status` stays `granted`
   - `verification_status=degraded`, `blocked`, or `error`
   - `status` remains a compatibility summary, not the source of truth

#### Dedicated flow

1. Create dedicated connection
   - `connection_type=dedicated`
   - `consent_status=required` or `unknown`
   - `verification_status=unknown`
2. Dedicated credential added or rotated
   - Connection remains non-ready until consent and verification succeed
3. Dedicated credential missing or invalid
   - `verification_status=blocked`
   - runtime reason code indicates dedicated credential problem

#### Migration review flow

- `connection_type` is still set to `platform` or `dedicated`
- `metadata.legacy_identity_review_required=true`
- audit and UI show the record needs explicit operator review before final cleanup

## 2. ProviderCredential

**Purpose**: Tenant-owned credential material used only for explicit dedicated connections.

### Fields

| Field | Type | Required | Notes |
|---|---|---:|---|
| `id` | bigint | yes | Existing primary key |
| `provider_connection_id` | bigint FK | yes | Existing one-to-one relationship |
| `type` | string | yes | Existing legacy type; retained temporarily for backward compatibility |
| `credential_kind` | string | no | New; `client_secret`, later `certificate` or `federated` |
| `source` | string | no | New; `dedicated_manual`, `dedicated_imported`, `legacy_migrated` |
| `payload` | encrypted array | yes | Existing encrypted payload, only for dedicated credentials |
| `created_at` / `updated_at` | timestamps | yes | Existing |

### Validation Rules

- `provider_connection_id` must reference a `ProviderConnection` with `connection_type=dedicated`.
- `payload` must contain the fields required by `credential_kind`.
- `client_secret` payloads must include a non-empty `client_id` and `client_secret`.
- `tenant_id` or authority hints inside the payload, if present, must match the parent connection’s target tenant.

### Relationships

- Belongs to one `ProviderConnection`

## 3. PlatformProviderIdentity

**Purpose**: Virtual central identity returned by the platform resolver. Not stored in tenant-owned tables.

### Fields

| Field | Type | Required | Notes |
|---|---|---:|---|
| `provider` | string | yes | `microsoft` |
| `client_id` | string | yes | Central multitenant app ID |
| `credential_mode` | string | yes | Initially `client_secret` |
| `client_secret` or `secret_reference` | string | yes | Resolved centrally; never copied into tenant tables |
| `authority_tenant` | string | yes | Usually platform home tenant or `organizations` routing metadata |
| `redirect_uri` | string | yes | Canonical callback route |
| `redirect_source` | string | yes | Metadata for display and debugging |

### Validation Rules

- `client_id` must be present for all platform flows.
- A secret or secret reference must be resolvable for runtime use.
- Redirect URI must match the canonical consent callback route.

## 4. ProviderIdentityResolution

**Purpose**: Virtual service result consumed by `ProviderGateway`, verification, and consent generation.

### Fields

| Field | Type | Required | Notes |
|---|---|---:|---|
| `connection_type` | string | yes | `platform` or `dedicated` |
| `effective_client_id` | string | yes | App identity used for consent and runtime |
| `credential_source` | string | yes | `platform_config` or dedicated credential source |
| `tenant_context` | string | yes | Target customer tenant for Graph calls |
| `resolved` | boolean | yes | Whether runtime resolution succeeded |
| `reason_code` | string nullable | no | Stable blocker when not resolved |
| `message` | string nullable | no | Sanitized operator-safe explanation |

## 5. MigrationClassificationResult

**Purpose**: Explicit migration outcome for existing provider connections.

### Fields

| Field | Type | Required | Notes |
|---|---|---:|---|
| `provider_connection_id` | bigint | yes | Record being classified |
| `suggested_connection_type` | string | yes | `platform` or `dedicated` |
| `review_required` | boolean | yes | True for contradictory hybrid cases |
| `signals` | array | yes | Evidence such as tenant app fields, credential payload, consent/runtime mismatch |
| `source` | string | yes | `migration_scan`, `operator_override`, or similar |

## 6. AuditLog Impact

This feature does not add a new audit table. It extends audit usage for:

- connection created
- connection type changed
- consent started
- consent succeeded or failed
- consent revoked or missing detected
- verification succeeded or failed
- dedicated credential created, rotated, or deleted
- migration classification applied
- migration review required flagged or resolved