TenantAtlas/specs/061-provider-foundation/data-model.md

Data Model: Provider Foundation v1

Branch: 061-provider-foundation
Date: 2026-01-24
Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/061-provider-foundation/spec.md

Entities

ProviderConnection

Represents a tenant-scoped connection to an external provider (v1: Microsoft).

Identity

• Scoped to a Suite Tenant (tenant_id).
• Canonical target scope identifier for Microsoft: entra_tenant_id (GUID).
• Uniqueness: (tenant_id, provider, entra_tenant_id) must be unique.

Fields (suggested)

• id (UUID)
• tenant_id (FK → tenants)
• provider (string; v1: microsoft)
• entra_tenant_id (string; GUID)
• display_name (string)
• is_default (boolean; exactly one default per (tenant_id, provider))
• status (string enum): connected | needs_consent | error | disabled
• health_status (string enum): ok | degraded | down
• scopes_granted (json/jsonb; optional; stores observed granted scopes/permissions metadata)
• last_health_check_at (timestamp nullable)
• last_error_reason_code (string nullable; stable reason code)
• last_error_message (string nullable; sanitized short message)
• metadata (json/jsonb nullable; optional non-sensitive provider metadata)
• timestamps

Indexes (suggested)

• Unique index: (tenant_id, provider, entra_tenant_id)
• Partial unique index: (tenant_id, provider) where is_default = true
• Indexes for filtering: (tenant_id, provider, status), (tenant_id, provider, health_status)

State transitions (v1)

• status: typically needs_consent/error → connected after successful health check; disabled is an explicit admin action.
• health_status: ok on successful check; degraded/down based on categorized failures (throttling vs outage vs auth).

---

ProviderCredential

Represents securely stored credentials for exactly one provider connection.

Identity

• 1:1 with ProviderConnection (provider_connection_id unique).

Fields (suggested)

• id (UUID)
• provider_connection_id (FK → provider_connections, unique)
• type (string; v1: client_secret)
• payload (encrypted JSON/array)
  • required keys (v1): client_id, client_secret
  • optional key: tenant_id (should match ProviderConnection entra_tenant_id if stored)
• timestamps

Constraints (suggested)

• payload must be encrypted at rest.
• payload must never be exposed via UI/API serialization.
• If payload.tenant_id is stored, validate it matches provider_connections.entra_tenant_id.

---

DefaultProviderConnection (concept)

Not a separate table by default; represented by provider_connections.is_default = true.

Rules:

• Multiple Microsoft connections per Suite Tenant are allowed.
• Exactly one default connection exists per (tenant_id, provider) and is used when starting operations without an explicit connection selection.

---

OperationRun (existing)

Provider operations are tracked as operation_runs with provider context stored in the context JSON.

Provider context fields (suggested)

• provider: microsoft
• provider_connection_id: UUID
• target_scope: { "entra_tenant_id": "<guid>" }
• module: health_check | inventory | compliance
• selection: optional selectors/filters for the operation (DB-only)
• idempotency: fingerprint/hash inputs used for dedupe

Concurrency rules (from spec clarifications)

• Same operation type + same scope: dedupe → return the active run.
• Different operation type while any run is active for the same scope: block as “scope busy” and link to the active run.