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.