TenantAtlas/specs/238-provider-identity-target-scope/quickstart.md

Quickstart: Provider Identity & Target Scope Neutrality

Goal

Implement the shared provider connection target-scope contract so generic provider surfaces stop treating Microsoft identity as the default meaning of a connection.

Implementation Sequence

1. Add the small shared target-scope descriptor and summary helper layer.
2. Refactor shared provider connection and identity-resolution outputs so neutral target-scope truth is available without Microsoft-shaped default labels.
3. Update provider connection list, detail, create, and edit surfaces to use neutral target-scope language by default.
4. Update the onboarding provider setup step and shared audit and validation wording to reuse the same neutral contract.
5. Add focused guardrails that block Microsoft-specific default labels, filters, required fields, validation messages, helper copy, and audit prose from reappearing on shared provider connection surfaces.

Suggested Code Areas

apps/platform/app/Filament/Resources/ProviderConnectionResource.php
apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
apps/platform/app/Services/Providers/
apps/platform/app/Support/Providers/TargetScope/
apps/platform/tests/Feature/Audit/
apps/platform/tests/Feature/Filament/
apps/platform/tests/Feature/ProviderConnections/
apps/platform/tests/Feature/Guards/
apps/platform/tests/Unit/Providers/

Verification Commands

Run the narrowest shared-contract proof first:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Providers/ProviderConnectionTargetScopeDescriptorTest.php tests/Unit/Providers/ProviderIdentityResolutionNeutralityTest.php tests/Unit/Providers/ProviderConnectionBadgeMappingTest.php tests/Unit/Badges/ProviderConnectionBadgesTest.php

Then run the shared-surface and onboarding proof:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php tests/Feature/ProviderConnections/ProviderConnectionViewsDbOnlyRenderingSpec081Test.php tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php tests/Feature/ManagedTenantOnboardingWizardTest.php

Then run the audit and guardrail proof:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Audit/ProviderConnectionIdentityAuditTest.php tests/Feature/Guards/ProviderConnectionNeutralityGuardTest.php

If PHP files changed, finish with formatting:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Review Focus

• Confirm shared provider connection forms, tables, and infolists no longer use Entra tenant ID as the default shared label or required field.
• Confirm the shared target-scope descriptor remains understandable without provider-specific vocabulary.
• Confirm unsupported provider or target-scope combinations and missing-context paths fail explicitly instead of inheriting Microsoft defaults.
• Confirm Microsoft tenant, directory, and consent details remain available only as contextual provider-owned metadata.
• Confirm unchanged 404 versus 403 behavior and confirmation-gated sensitive actions are preserved on the touched shared surfaces.
• Confirm onboarding uses the same target-scope meaning as the provider connection resource.
• Confirm audit and validation wording follow the same provider and target-scope vocabulary.
• Confirm no broader credential-model, second-provider, or marketplace scope slipped into the slice.

Guardrail Close-Out

• Validation to complete before final handoff:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Providers/ProviderConnectionTargetScopeDescriptorTest.php tests/Unit/Providers/ProviderIdentityResolutionNeutralityTest.php tests/Unit/Providers/ProviderConnectionBadgeMappingTest.php tests/Unit/Badges/ProviderConnectionBadgesTest.php tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php tests/Feature/ProviderConnections/ProviderConnectionViewsDbOnlyRenderingSpec081Test.php tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php tests/Feature/ManagedTenantOnboardingWizardTest.php tests/Feature/Audit/ProviderConnectionIdentityAuditTest.php tests/Feature/Guards/ProviderConnectionNeutralityGuardTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
• Guardrails checked:
  • No new provider runtime or provider marketplace abstraction.
  • No new persistence or schema rewrite.
  • No Microsoft-specific default labels, filters, required fields, validation messages, helper copy, or audit prose on shared provider connection surfaces.
  • Unchanged 404 versus 403 behavior and confirmation-gated sensitive actions remain intact on the touched shared surfaces.
  • Microsoft contextual identity remains available where current-release workflows genuinely need it.
• Implemented close-out:
  • Shared provider connection surfaces now use Target scope vocabulary by default.
  • Provider-owned Microsoft details are carried in provider_identity_context and diagnostic labels such as Microsoft tenant ID.
  • Create, update, verification, health-check, and onboarding audit metadata carries target_scope plus provider context instead of promoting a raw Microsoft tenant field as shared truth.
  • Existing Filament table contracts for provider connections were updated to reflect provider and target scope as default-visible summary columns.
• Close-out decision: document-in-feature. The shared provider connection target-scope hotspot is closed here; broader cross-domain provider-boundary work remains separately tracked.