TenantAtlas/specs/081-provider-connection-cutover/research.md

Research: Provider Connection Full Cutover

Feature: specs/081-provider-connection-cutover/spec.md
Date: 2026-02-07

Goal

Resolve repo-specific unknowns for the full credential cutover, and document decisions with rationale and alternatives.

Findings (Repo Reality)

Existing ProviderConnection / ProviderCredential primitives

• ProviderConnection exists as a workspace-owned, tenant-scoped integration asset.
• Default invariant already exists at DB level via partial unique index:
  • provider_connections_default_unique on (tenant_id, provider) where is_default = true.
• ProviderCredential exists and stores encrypted payload in payload (encrypted:array) and is hidden from serialization.
• ProviderGateway::graphOptions(ProviderConnection $connection) builds Graph options using CredentialManager.

Existing runtime provider call patterns

• Some jobs are already ProviderConnection-first:

  • Provider connection health check uses ProviderGateway::graphOptions($connection).
  • Provider operation start gate (ProviderOperationStartGate) uses provider_connection_id in operation run context and dedupe.

• Legacy tenant credential reads still exist in high-impact services and UI:

  • Services: inventory sync, policy sync, policy snapshots/backups, restore, RBAC onboarding, scope tag resolver.
  • UI: tenant registration + tenant resource form exposes app_client_id / app_client_secret.

Operations / observability primitives

• OperationRun has:
  • status: queued|running|completed
  • outcome: pending|succeeded|partially_succeeded|failed (+ reserved cancelled)
  • context JSON field used for identity and target scope.
• Provider operation start gate already writes context.provider, context.provider_connection_id, and context.target_scope.entra_tenant_id.

Decisions

D1 — Single Source of Truth: ProviderConnection + ProviderCredential

Decision: All runtime provider calls use ProviderConnection + ProviderCredential via ProviderGateway.

Rationale: Eliminates drift between verification vs restore and makes the suite deterministic and auditable.

Alternatives considered:

• Continue dual-source (tenant fields + provider connections): rejected due to drift and security risk.
• Allow runtime fallback to tenant fields: rejected; violates “single read path” and creates non-determinism.

D2 — Default enforcement applies to all providers; backfill creates Microsoft defaults only

Decision: The invariant “exactly one default per (tenant, provider)” is generic for all providers, but the one-time backfill only creates/repairs defaults for provider microsoft.

Rationale: Keeps the suite future-proof while delivering Microsoft-only cutover now.

Alternatives considered:

• Microsoft-only invariant: rejected; forces future migrations and special cases.

D3 — Blocked starts still create an OperationRun

Decision: Starting a provider-backed operation without usable configuration still creates an OperationRun record to preserve observability.

Rationale: Operators need a canonical record for “what was attempted” and why it is blocked.

Alternatives considered:

• UI-only blocked banner without a run: rejected; loses auditability/observability.

D4 — Represent “blocked” runs as a distinct OperationRun outcome

Decision: Introduce a blocked outcome on operation runs (keep status lifecycle unchanged: completed).

Rationale: The repo currently has no “blocked” status/outcome for runs; representing it explicitly prevents conflating blocked with failed.

Alternatives considered:

• Encode blocked as outcome=failed + reason_code: rejected; UI semantics become inconsistent and ambiguous.
• Add a new status value (blocked): rejected; affects active-run dedupe and status badge expectations more broadly.

D5 — Backfill selection rule for existing connections without a default

Decision: If exactly one Microsoft provider connection exists, set it default. If multiple exist, do not auto-select (requires admin remediation).

Rationale: Avoids accidental selection of the wrong app registration.

Alternatives considered:

• Always pick the oldest: rejected; unsafe in enterprise environments.
• Always create a new connection: rejected; increases clutter and may violate tenant/provider/entra uniqueness.

D6 — Legacy tenant credential reads allowed only in explicit backfill tooling

Decision: Legacy tenant fields (tenants.app_*) are forbidden in runtime and permitted only in backfill command/migration.

Rationale: Tightens the security posture and makes cutover verifiable via guard tests.

Alternatives considered:

• Runtime fallback: rejected.
• No backfill reads: rejected; forces manual secret re-entry for all tenants.

Open Points (to be handled in implementation)

• Centralize “next steps” as link keys (the repo currently embeds Filament URLs directly in verification checks).
• Determine the final reason_code taxonomy mapping for common exceptions (credential missing, auth failure, tenant mismatch).