Design: Add Authority Refactoring design documentation with registry + pipeline architecture

[Copilot]

Authority Refactoring Design Documents

Adds comprehensive design documentation for the planned authority refactoring initiative in MSAL.NET, establishing team alignment before implementation begins.

Overview

This PR introduces two companion design documents that specify a Registry + Pipeline architecture for authority creation and validation:

1. AUTHORITY_REFACTORING_DESIGN.md — Complete design specification covering architecture, goals, test strategy, backwards compatibility, and phased rollout plan
2. AUTHORITY_REFACTORING_ARCHITECTURE.md — Architecture diagrams, data flow, registry lookup paths, and code location impact analysis

Key Design Principles

• Single Registry — AuthorityRegistry centralizes all authority type metadata (detection, creation, validation, resolution)
• Deterministic Pipeline — All authority creation flows through a documented 6-step AuthorityCreationPipeline
• Zero Regressions — Comprehensive characterization tests capture all observable behaviors before any production code changes
• Additive Extensibility — Adding a new authority type requires changes only to the registry, not to the pipeline or callers

Architecture Highlights

Current (Fragile)

• Type detection scattered across AuthorityInfo.DetectAuthorityType()
• Factory logic in Authority.CreateAuthority() switch statement
• No single source of truth for "what is an X authority?"
• Adding a new type requires touching 5+ files

Proposed (Centralized)

• AuthorityRegistration records define all metadata for each type
• AuthorityRegistry provides detection and lookup via registration order
• AuthorityCreationPipeline orchestrates 6 deterministic steps:
  1. Parse — Validate URI format
  2. Detect — Identify authority type via registry
  3. Normalize — Apply type-specific URI canonicalization
  4. Merge — Combine config-level and request-level authorities with environment overrides
  5. Validate — Run type-specific validation (AAD: instance discovery, ADFS: WebFinger, others: no-op)
  6. Construct — Instantiate concrete Authority subclass

Extensibility

Adding a hypothetical FabrikamAuthority requires:

• Create FabrikamAuthorityRegistration.cs (one file)
• Add one line to AuthorityRegistry static constructor

No changes needed in AuthorityInfo, Authority, AuthorityManager, or pipeline logic.

Test Strategy

Six categories of characterization tests (before any production code changes):

1. Detection Tests — Authority type detection is correct for all 6 types
2. Normalization Tests — URI canonicalization produces expected form
3. Endpoint Construction Tests — Token endpoint URLs are correct
4. MSA Passthrough Tests — Personal accounts inject consumers tenant
5. Environment Override Tests — Sovereign cloud aliases work correctly
6. Error Message Tests — Exception messages are preserved

Phased Rollout Plan

Phase	Goal	Deliverables
1	Regression safety net	Characterization tests (all passing on main)
2	Infrastructure	Registry, pipeline, normalizers (internal only, no callers)
3	Integration	Wire up pipeline in AuthorityManager
4	Cleanup	Remove legacy code paths, update documentation

Backwards Compatibility

• Public API — No changes; WithAuthority() methods unchanged
• Behavioral — All behaviors preserved (token endpoints, tenant handling, MSA passthrough, environment override, error codes)
• Internal — Selected types refactored; callers updated atomically in the same PR

Files Changed

• ✅ docs/design/AUTHORITY_REFACTORING_DESIGN.md (685 lines) — Complete design spec with test examples
• ✅ docs/design/AUTHORITY_REFACTORING_ARCHITECTURE.md (471 lines) — Diagrams, data flow, dependency graphs

Scope

Documentation only — no executable code changes. This PR serves as the design specification for the implementation PR that will follow after team review and approval.

Success Criteria

1. All characterization tests pass before and after implementation
2. No test regressions relative to main
3. New authority types require changes in ≤2 files
4. No duplicate type-detection logic in Instance/ namespace
5. Code coverage maintained or improved
6. Design approved by ≥2 MSAL.NET maintainers

[christothes]

Could this be static?