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

# Exchange Source Surface Catalog

Spec 429 catalog status: documentation only. This file does not create runtime support, provider calls, evidence, OperationRuns, restore behavior, customer claims, UI, or app-side documentation lookup.

## Source References

Official Microsoft references reviewed for this catalog:

- [Exchange Online PowerShell](https://learn.microsoft.com/en-us/powershell/exchange/exchange-online-powershell?view=exchange-ps)
- [App-only authentication for unattended scripts in Exchange Online PowerShell and Security & Compliance PowerShell](https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps)
- [Exchange PowerShell cmdlet module reference](https://learn.microsoft.com/en-us/powershell/module/exchangepowershell/?view=exchange-ps)
- [Overview of the Exchange Online Admin API](https://learn.microsoft.com/en-us/exchange/reference/admin-api-overview)
- [Authentication and authorization for the Exchange Online Admin API](https://learn.microsoft.com/en-us/exchange/reference/admin-api-authentication)
- [Manage mail flow rules in Exchange Online](https://learn.microsoft.com/en-us/exchange/security-and-compliance/mail-flow-rules/manage-mail-flow-rules)
- [Manage accepted domains in Exchange Online](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/manage-accepted-domains/manage-accepted-domains)
- [Remote domains in Exchange Online](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/remote-domains/remote-domains)

Repo references:

- `apps/platform/app/Services/TenantConfiguration/ResourceTypeRegistry.php`
- `apps/platform/app/Services/TenantConfiguration/SupportedScopeResolver.php`
- `apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php`
- `apps/platform/app/Services/TenantConfiguration/CoverageIdentityStrategyRegistry.php`
- `specs/419-m365-tcm-workload-registry-expansion/implementation-report.md`
- `specs/420-m365-generic-evidence-coverage-pack/implementation-report.md`
- `specs/422-exchange-teams-comparable-renderable-pack/implementation-report.md`
- `specs/426-exchange-teams-core-evidence-identity-readiness/implementation-report.md`
- `specs/427-exchange-teams-verified-source-contract-enablement/implementation-report.md`
- `specs/428-exchange-teams-content-backed-evidence-promotion/spec.md`

## Current Repo Truth

- `ResourceTypeRegistry` has registry-only Exchange planning rows for `transportRule`, `acceptedDomain`, `sharedMailbox`, `remoteDomain`, `mailboxPlan`, and `organizationConfig`.
- `SupportedScopeResolver` keeps Exchange planning scopes inactive and not customer-claimable.
- `CoverageSourceContractResolver` explicitly keeps `transportRule` and `acceptedDomain` blocked as `contract_blocked_repo_adapter_missing`; no provider call, evidence promotion, restore, certification, or customer claim is allowed.
- `CoverageIdentityStrategyRegistry` has stable candidate identity strategies for `transportRule` and `acceptedDomain`, but those strategies do not make source capture available.
- Spec 426 removed unverified Graph endpoint claims for Exchange/Teams first types.
- Spec 427 records the final source-contract state as blocked until a repo adapter/source contract exists.
- Spec 428 is prepared as fail-safe/no-op context; it is not implemented evidence.

## Source Surface Classes

| Source surface class | Exchange meaning | Adapter pattern | Current Spec 429 posture |
| --- | --- | --- | --- |
| `exchange_online_powershell_rest` | Exchange Online PowerShell module and REST-backed cmdlets. Broadest administrative surface for mail flow, domains, connectors, organization, sharing, mailbox plan, and related configuration. | `new_exchange_powershell_adapter` | Candidate for most Cohort 1 Exchange types. Requires app-only auth, least-privilege RBAC, command allowlist, fake command runner tests, throttling/error normalization, response serialization, and redaction. |
| `exchange_online_admin_api` | Preview REST-based administrative surface for a focused set of Exchange scenarios such as `OrganizationConfig` and `AcceptedDomain`. It is POST-only and is not a full Exchange Online PowerShell replacement. | `new_exchange_admin_api_contract` | Candidate only for accepted-domain and organization-config style reads when availability and RBAC can be proven. Preview status blocks certification/customer claims. |
| `security_compliance_powershell` | Purview/Security & Compliance PowerShell boundaries for retention, sensitivity, DLP, audit, and compliance artifacts. | `new_security_compliance_adapter` or `defer_to_purview_adapter` | Boundary/deferred for Spec 429 Exchange catalog. Do not mix with Exchange Cohort 1 unless a later Purview spec justifies it. |
| `unsupported_manual_only` | Portal-only, unsafe, destructive, or operational-action surfaces. | `unsupported` | Excluded from Cohort 1. |
| `unknown_requires_research` | Source unclear or official docs do not support a safe capture decision. | `unsupported` until researched | Excluded from Cohort 1. |

## Exchange Family Catalog

| Family | Candidate target types | Source surface class | Adapter pattern | Expected object shape | Identity risk | Permission risk | Response shape risk | Redaction risk | Customer/MSP value | Cohort posture |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Mail flow and transport | `transportRule`, `transportConfig` | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Mostly collections for rules plus tenant singleton/config objects. | Medium: rules have GUID-like identifiers, but display names and order are not stable identity. | High: mail-flow roles are sensitive and changes can affect message routing. | Medium: conditions/actions/exceptions are nested and order-sensitive. | High: rules can contain subject/body/header/disclaimer patterns. | High customer and MSP value because mail-flow rules are critical configuration. | `transportRule` is Cohort 1 selected; `transportConfig` is Cohort 2. |
| Domains and connectors | `acceptedDomain`, `remoteDomain`, `inboundConnector`, `outboundConnector` | `exchange_online_admin_api` for accepted-domain/org reads where safe; otherwise `exchange_online_powershell_rest`. | `new_exchange_admin_api_contract` or `new_exchange_powershell_adapter` | Collections keyed by domain/connector identifiers; connector objects include routing/security settings. | Low to medium: domain names can be natural keys; connector names are display-like and need source IDs. | Medium/high: domain and connector reads reveal mail routing posture. | Medium: connector shapes vary and may contain endpoint details. | Medium: connectors may include smart-host and organization routing data. | High value for migration, mail-flow, and MSP posture review. | `acceptedDomain`, `remoteDomain`, `inboundConnector`, and `outboundConnector` are Cohort 1 selected. |
| Organization configuration | `organizationConfig`, `transportConfig` | `exchange_online_admin_api` where the focused API covers it; otherwise `exchange_online_powershell_rest`. | `new_exchange_admin_api_contract` or `new_exchange_powershell_adapter` | Tenant singleton settings. | Low: singleton identity can derive from workspace + managed environment + provider connection + canonical type. | Medium/high: broad organization roles may be required. | Medium: singleton fields can be large and version-dependent. | Medium: org settings can contain domains and routing hints. | High value for baseline and drift review. | `organizationConfig` is Cohort 1 selected; broader config is Cohort 2. |
| Sharing and relationship configuration | `sharingPolicy`, `organizationRelationship`, `availabilityAddressSpace` | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Collections with policy/relationship objects. | Medium: names are not enough; source IDs or stable composite keys needed. | Medium: external sharing configuration is sensitive. | Medium: external-org fields and federation state vary. | Medium: partner domain and relationship metadata need redaction discipline. | Medium/high value for external collaboration posture. | `sharingPolicy` is Cohort 1 selected; relationship variants are Cohort 2. |
| Protection and hygiene boundary | `antiPhishPolicy`, `antiSpamPolicy`, `safeLinksPolicy`, `malwareFilterPolicy` | `security_compliance_powershell` or Exchange-adjacent cmdlets depending on exact object. | `new_security_compliance_adapter` or `defer_to_purview_adapter` | Collections of policy objects and rules. | Medium/high: policy and rule identity can be split. | High: Defender/Purview permissions may exceed Exchange least privilege. | High: policy/rule joins and portal behavior can be complex. | High: rule conditions may include domains, senders, subjects, or content patterns. | High value, but boundary risk is high. | Deferred to Purview/Defender boundary work. |
| Recipient and mailbox boundary | `sharedMailbox`, `mailboxPlan`, `mailboxFolderPermission`, `sendOnBehalfDelegation` | `exchange_online_powershell_rest`; Admin API only for focused mailbox/folder/delegation scenarios. | `new_exchange_powershell_adapter` or `new_exchange_admin_api_contract` | Collections or per-mailbox data; high cardinality risk for mailbox-scoped objects. | Medium/high: mailbox and permission identities need stable source IDs. | High: recipient/mailbox roles are broad and can expose user data. | High for per-mailbox enumeration and paging. | Critical for mailbox content-adjacent permissions and PII. | Mixed: mailbox plan high for governance; per-mailbox data needs stronger scope. | `mailboxPlan` is Cohort 1 selected; `sharedMailbox` and per-mailbox permissions are Cohort 2/deferred. |
| Role assignment and admin audit | `managementRoleAssignment`, `adminAuditLogConfig` | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Collections for assignments; singleton for audit config. | Medium: role assignment identity can be composite. | Critical: role/admin audit data is highly sensitive. | Medium/high: assignments may reference users/groups/service principals. | High: role assignments include principals and privileged admin metadata. | High operator value but high security review cost. | Cohort 2 or deferred until RBAC/audit redaction is separately reviewed. |
| Purview/Security & Compliance boundary | `labelPolicy`, `retentionCompliancePolicy`, `dlpCompliancePolicy`, `autoSensitivityLabelPolicy`, `protectionAlert`, `complianceTag` | `security_compliance_powershell` | `new_security_compliance_adapter` or `defer_to_purview_adapter` | Collections, sometimes policy/rule pairs. | Medium/high. | Critical: compliance roles and content-sensitive policy scope. | High: workloads and portals overlap. | Critical: compliance data can contain sensitive labels/rules. | High future value; not Exchange Cohort 1. | Deferred; requires a Purview/Security & Compliance adapter strategy. |

## Exchange Cohort Guidance

Cohort 1 should use Exchange Online PowerShell as the first practical Exchange source surface, with Exchange Admin API treated as a narrow optional path for `acceptedDomain` and `organizationConfig` if preview availability and RBAC are acceptable. Cohort 1 must still start blocked in runtime until Spec 430 implements an adapter and tests it with a fake command/API runner. It must not infer Graph availability from display aliases such as `mailFlowRule` or `acceptedDomains`.

## Forbidden Source Authority Rules

- Do not treat Microsoft Learn examples as runtime contracts.
- Do not create Graph contracts for Exchange target types unless official Graph availability and repo contract shape are proven in a later spec.
- Do not use Exchange Admin API as a full Exchange Online PowerShell replacement.
- Do not execute shell commands in unit tests.
- Do not store certificates, private keys, client secrets, access tokens, raw provider responses, mail content, or message content in catalog artifacts, audit metadata, OperationRun context, or default-visible output.
- Do not treat `tenant_id` as platform-core ownership truth; later runtime records must use workspace + managed environment + provider connection boundaries.