# 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.