TenantAtlas/specs/139-verify-access-permissions-assist/contracts/verification-link-behavior.md

Verification Link Behavior Contract — Spec 139

Purpose

Define how Verify Access remediation controls and deep-dive links behave so the onboarding tab is preserved while deeper investigation remains available.

Surfaces covered

• Verify Access report remediation controls rendered from managed-tenant-onboarding-verification-report.blade.php
• The in-place Required Permissions assist slideover

Link categories

1) Assist-routed remediation controls

• Examples:
  • Grant admin consent shown directly in the Verify Access report for permission-related checks
  • Review platform connection shown directly in the Verify Access report for permission-related checks
• Behavior:
  • Must open the in-place Required Permissions assist instead of navigating away.
  • Must keep the current onboarding tab and wizard step intact.
  • Must make it clear that the operator is opening the assist, not leaving the wizard.

2) External remediation links

• Examples:
  • Admin consent URLs
  • Microsoft Learn guidance URLs
• Behavior:
  • Must open in a new tab.
  • Must retain rel protection.
  • Must be visually or semantically clear that they open a new tab.

3) Internal diagnostic deep-dive links

• Examples:
  • Existing Required Permissions full page
  • Relevant provider-connection diagnostic pages linked from verification next steps
  • Other operator investigation pages that intentionally leave the wizard context and explicitly opt into diagnostic behavior
• Behavior:
  • Must open in a new tab when launched from Verify Access or the assist.
  • Must not replace the onboarding tab.
  • Must be visually or semantically clear that they open a new tab.

Concrete classification rules

External remediation links

• Match absolute http:// and https:// URLs.
• Examples:
  • RequiredPermissionsLinks::adminConsentUrl(...)
  • RequiredPermissionsLinks::adminConsentGuideUrl()

Internal diagnostic deep-dive links

• Match internal admin URLs that intentionally leave the in-place recovery flow for investigation.
• The initial allowlist for Spec 139 is:
  • RequiredPermissionsLinks::requiredPermissions(...)
  • Admin Provider Connection management URLs generated by ProviderConnectionResource::getUrl('index'|'view'|'edit', ..., panel: 'admin')
• Any future internal diagnostic deep-dive URL must opt in through the shared VerificationLinkBehavior helper rather than adding ad-hoc Blade conditions.

Internal inline-safe links or actions

• Anything that stays inside the current onboarding interaction remains same-tab.
• Examples:
  • Existing wizard actions such as rerun verification
  • Slideover close/dismiss controls
  • Non-navigation UI toggles

4) Internal inline-safe actions

• Examples:
  • Existing in-component rerun verification action
  • Slideover close action
• Behavior:
  • Must remain in the current onboarding tab.
  • Must not be converted into link-based new-tab navigation.

Required semantics

• Permission-related remediation controls in the Verify Access report are always category 1.
• The full-page Required Permissions action inside the assist is always category 3.
• Existing external links exposed from the assist remain category 2.
• Verification-report rendering must no longer assume that permission remediation should navigate directly when the assist is available.
• Link and remediation classification must be rule-based and reusable so additional permission-related checks can route through the assist without view-level duplication.
• The helper must distinguish provider-connection management routes from same-tab onboarding controls so the onboarding tab is preserved only for true diagnostic escapes.

Explicit non-goals

• No new routes.
• No same-tab replacement of the onboarding wizard for category 2 or category 3 links.
• No conversion of the Required Permissions page into an onboarding sub-step.