TenantAtlas/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md

Adapter Strategy

Spec 429 catalog status: documentation only. This file does not create adapters, clients, provider calls, tests, evidence, OperationRuns, UI, or runtime registry consumption.

Source Authority Rules

Allowed source authority for future specs:

• Official Microsoft documentation for source surface availability, authentication, authorization, and API/cmdlet behavior.
• Current repo contracts and tests for TenantPilot runtime truth.
• Existing Coverage v2 source-contract, identity, evidence, compare/render, Claim Guard, OperationRun, workspace/managed-environment/provider-connection, and redaction patterns.

Forbidden source authority:

• Guessed Microsoft Graph endpoints.
• Admin portal UI pages as runtime source contracts.
• PowerShell examples as proof that TenantPilot has runtime support.
• Registry aliases as evidence support.
• Historical completed specs as mutable artifacts.
• Display names as stable identity.
• tenant_id as platform-core ownership truth.
• Real shell execution in unit tests.

Adapter Pattern Matrix

Adapter pattern	Source surface class	Use when	Required future implementation constraints	Spec 429 decision
existing_graph_client_contract	graph_v1	A repo Graph contract already exists and is production-safe.	Must go through GraphClientInterface and config/graph_contracts.php; no render-time Graph call; tests must prove scope, permissions, pagination, identity, redaction, and no customer overclaim.	Not used for current Exchange/Teams policy Cohort 1.
new_graph_contract	graph_v1 or graph_beta_experimental	Official Graph source exists and policy/resource shape fits Coverage v2.	Add contract registry entry, permission review, pagination, allowed select/expand, schema hash, fake Graph tests, and beta/internal-only handling where needed.	Deferred for Teams inventory/app-installation style future work; not the first adapter path.
new_exchange_admin_api_contract	exchange_online_admin_api	The focused preview Admin API supports the target and preview/internal-only limitations are acceptable.	OAuth token path, Exchange RBAC role groups, POST-only endpoint handling, X-AnchorMailbox handling if required, paging/property selection, response-shape guard, preview no-certification rule, fake HTTP tests.	Candidate for acceptedDomain and organizationConfig; not a full Exchange replacement.
new_exchange_powershell_adapter	exchange_online_powershell_rest	Exchange source truth is only in Exchange Online PowerShell or the Admin API is too narrow/preview-limited.	App-only/certificate or managed identity feasibility, Exchange RBAC, command allowlist, no arbitrary script execution, fake command runner, module/runtime container decision, throttling/retry, structured errors, redaction, source metadata, OperationRun for real remote work.	Recommended first Spec 430 adapter pattern.
new_teams_powershell_adapter	teams_powershell	Teams policy/configuration source truth is in MicrosoftTeams PowerShell.	Application-based authentication, Teams RBAC roles, supported-cmdlet check, command allowlist, fake command runner, module/runtime container decision, throttling/retry, structured errors, redaction, source metadata, OperationRun for real remote work.	Recommended second slice after Exchange PowerShell proof, or reduced paired slice if Spec 430 must cover both workloads.
new_security_compliance_adapter	security_compliance_powershell	Purview/Security & Compliance policy source truth is explicitly in compliance PowerShell.	Separate security review, role/permission minimization, content-sensitive redaction, no customer claims until proven, fake command runner, OperationRun for remote work.	Deferred; not part of Exchange/Teams Cohort 1.
defer_to_purview_adapter	security_compliance_powershell	The target is primarily Purview/Defender/Compliance rather than Exchange/Teams.	Create a separate Purview/Security & Compliance source-surface strategy/spec.	Deferred.
unsupported	unsupported_manual_only, unknown_requires_research, sharepoint_pnp_related	Source is manual, unknown, portal-only, or belongs to another workload boundary.	Do not implement; document blocker.	Blocked/deferred.

Graph Contract Concerns

Future Graph-based Teams work must answer:

• Is the resource available in Graph v1.0, or only beta?
• Does the resource represent durable configuration, or collaboration/content activity?
• Which Graph application/delegated permissions are required?
• Does the endpoint page, delta, select, expand, or filter?
• Which identity fields are stable across tenants and exports?
• Does the response include chat/message/file/recording/transcript/content or other forbidden data?
• Can the existing GraphClientInterface and config/graph_contracts.php model the endpoint without a new provider framework?
• How are empty, denied, unsupported, unavailable, throttled, and malformed responses distinguished?

Spec 429 does not select a Graph-native policy path for Exchange/Teams Cohort 1 because current repo truth already removed unverified Graph endpoint claims for the first four Exchange/Teams target types.

Exchange Online Admin API Concerns

The Exchange Online Admin API is a focused preview REST administrative surface. Future use must document:

• Preview status and tenant availability.
• Supported endpoint and cmdlet subset.
• Unsupported scenarios and why the API does not replace Exchange Online PowerShell.
• OAuth flow: delegated Exchange.ManageV2 or app-only Exchange.ManageAsAppV2.
• Exchange RBAC role groups and least-privilege custom role options.
• POST-only request model.
• Paging/property selection.
• X-AnchorMailbox/routing requirements where applicable.
• Response shape, empty result, denied result, unsupported result, unavailable result, and malformed result handling.
• Preview/internal-only claim posture: no certification or customer-ready claim from preview-only source proof.

Spec 429 treats acceptedDomain and organizationConfig as Admin API candidates but does not make them runtime-supported.

Exchange PowerShell Adapter Concerns

A future new_exchange_powershell_adapter must include:

• Authentication: app-only certificate-based authentication or managed identity where supported by deployment topology.
• Tenant consent: required Office 365 Exchange Online application permissions and admin consent must be explicit.
• RBAC: least-privilege Exchange role group or custom role group, not broad Global Administrator by default.
• Execution environment: container image/module installation, PowerShell version, module version pinning/update policy, non-interactive execution, timeout handling, and process isolation.
• Command allowlist: only approved read cmdlets and approved parameters.
• No shell execution in unit tests: use a fake command runner with deterministic serialized outputs.
• Throttling and retries: classify throttled/transient failures separately from denied/unsupported/source-unavailable.
• Error normalization: sanitize command errors and map to stable reason codes.
• Response serialization: canonical JSON with sorted keys where appropriate, source version, command name, parameter hash, schema/hash metadata, and no raw terminal transcript by default.
• Redaction: remove or hide secrets, tokens, credentials, authorization headers, certificate/private-key material, raw provider responses, mail content, message content, header/body/subject patterns where unsafe, smart hosts when unsafe, and PII-heavy fields.
• OperationRun: real provider execution is remote/long-running and must be OperationRun-backed in a later runtime spec.

Recommended first Exchange runtime proof:

• transportRule
• remoteDomain
• one connector type, preferably inboundConnector first if a later spec confirms source output shape

Do not include sharedMailbox, managementRoleAssignment, or compliance policies in the first Exchange adapter slice.

Teams PowerShell Adapter Concerns

A future new_teams_powershell_adapter must include:

• Authentication: application-based authentication with certificate or access-token flow, plus explicit Teams module version support.
• RBAC: Microsoft Entra roles and Teams admin roles assigned to the application/service principal; verify supported cmdlets and unsupported cmdlet list.
• Permissions: Graph permissions required by Teams PowerShell application authentication must be explicit, while avoiding unnecessary Skype and Teams Tenant Admin API configuration where Microsoft guidance warns against it.
• Execution environment: module installation, PowerShell runtime, container compatibility, non-interactive execution, timeout handling, and process isolation.
• Command allowlist: only approved read cmdlets and parameters.
• No shell execution in unit tests: use a fake command runner.
• Response serialization: canonical shape with source command, module version, policy ID/source ID, and schema/hash metadata.
• Error normalization: distinguish empty, denied, unsupported, source-unavailable, throttled, and malformed output.
• Redaction: never capture or default-render chat messages, file content, meeting recordings, transcripts, app secrets, app credentials, raw provider responses, or raw access tokens.
• OperationRun: real provider execution is remote/long-running and must be OperationRun-backed in a later runtime spec.

Recommended first Teams runtime proof:

• appPermissionPolicy
• appSetupPolicy
• meetingPolicy

Do not include voice/phone-number policy, team/channel inventory, app-centric management migration, or SharePoint/OneDrive file governance in the first Teams adapter slice.

Security & Compliance / Purview Boundary

Targets such as dlpCompliancePolicy, labelPolicy, retentionCompliancePolicy, autoSensitivityLabelPolicy, protectionAlert, and complianceTag are not Exchange/Teams Cohort 1. They need a separate Purview/Security & Compliance adapter strategy because they can involve:

• compliance-specific roles and permissions,
• content-sensitive policy scopes,
• retention/legal/compliance meaning,
• Defender/Purview portal overlap,
• stronger redaction and customer-output controls.

Unsupported / Unknown Follow-Up Paths

• Portal-only settings stay unsupported until official automation support is found.
• Unknown policy families stay unknown_requires_research.
• Teams files/storage governance belongs to SharePoint/OneDrive/PnP follow-up, not Teams policy capture.
• Microsoft cmdlets that perform operational actions rather than durable configuration reads are not target types.

First Spec 430 Implementation Slice

Recommended first adapter pattern: new_exchange_powershell_adapter.

Why this should come first:

• It addresses the highest-value Exchange blocker (transportRule) that Spec 426/427 intentionally kept blocked.
• It proves the hardest shared constraints early: process isolation, command allowlist, fake command runner, redaction, stable source metadata, and response-shape distinction.
• It avoids depending on the preview Exchange Admin API for the first runtime proof.
• It creates a reusable but narrow command-runner pattern that the Teams PowerShell adapter can mirror only after Exchange proves the constraints.

Spec 430 minimum scope should be:

• Implement a read-only Exchange PowerShell adapter with no arbitrary command execution.
• Use a fake command runner in unit tests and no shell execution in unit tests.
• Capture only transportRule, remoteDomain, and one connector type if the official source shape is verified in the spec.
• Preserve workspace + managed environment + provider connection ownership.
• Create/reuse OperationRun for any real provider execution.
• Add RBAC/policy tests, provider-scope tests, redaction tests, blocked/denied/unavailable tests, and no-customer-claim tests.
• Keep UI/browser proof N/A unless rendered product surfaces change.

Stop conditions for Spec 430:

• PowerShell execution cannot be isolated safely in the container runtime.
• Least-privilege Exchange RBAC cannot be defined.
• The adapter cannot distinguish empty, denied, unsupported, unavailable, throttled, and malformed responses.
• Redaction cannot safely prevent mail/message/header/body content exposure.
• Implementation requires tenant_id, legacy shims, fallback readers, dual writes, or customer claims.
• Implementation needs broad Exchange/Teams/Purview/SharePoint mini-platform work.

If both Exchange and Teams must ship in Spec 430, reduce the scope to two Exchange and two Teams types and explicitly document the extra fixture/runtime cost.