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

# Teams 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:

- [MicrosoftTeams PowerShell module reference](https://learn.microsoft.com/en-us/powershell/module/microsoftteams/?view=teams-ps)
- [Connect-MicrosoftTeams](https://learn.microsoft.com/en-us/powershell/module/microsoftteams/connect-microsoftteams?view=teams-ps)
- [Application-based authentication in Teams PowerShell Module](https://learn.microsoft.com/en-us/microsoftteams/teams-powershell-application-authentication)
- [Use app permission policies to control user access to apps](https://learn.microsoft.com/en-us/microsoftteams/teams-app-permission-policies)
- [Use setup policies to manage, install and pin agents and apps for users](https://learn.microsoft.com/en-us/microsoftteams/teams-app-setup-policies)
- [Teams settings and policies reference](https://learn.microsoft.com/en-us/microsoftteams/settings-policies-reference)
- [Use guest access and external access to collaborate with people outside your organization](https://learn.microsoft.com/en-us/microsoftteams/communicate-with-users-from-other-organizations)
- [Use the Microsoft Graph API to work with Microsoft Teams](https://learn.microsoft.com/en-us/graph/api/resources/teams-api-overview?view=graph-rest-1.0)

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 Teams planning rows for `appPermissionPolicy`, `appSetupPolicy`, `meetingPolicy`, `messagingPolicy`, `teamsUpdateManagementPolicy`, and `voiceRoute`.
- `SupportedScopeResolver` keeps Teams planning scopes inactive and not customer-claimable.
- `CoverageSourceContractResolver` explicitly keeps `appPermissionPolicy` and `meetingPolicy` 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 `appPermissionPolicy` and `meetingPolicy`, but those strategies do not make source capture available.
- Spec 422 can compare/render selected Teams payload shapes only when content-backed evidence exists. It does not prove live capture.
- Spec 428 is prepared as fail-safe/no-op context; it is not implemented evidence.

## Source Surface Classes

| Source surface class | Teams meaning | Adapter pattern | Current Spec 429 posture |
| --- | --- | --- | --- |
| `teams_powershell` | MicrosoftTeams PowerShell module policy/configuration cmdlets. Application-based authentication is supported with caveats and documented unsupported cmdlets. | `new_teams_powershell_adapter` | Primary Teams policy source candidate. Requires app-based auth, Teams RBAC role assignment, command allowlist, fake command runner tests, response serialization, throttling/error handling, and redaction. |
| `graph_v1` | Microsoft Graph Teams resources for teams, channels, tabs, app installations, chats, online meetings, call records, and related collaboration resources. | `new_graph_contract` or `existing_graph_client_contract` | Useful for teams/channels/app-installation inventory, but not sufficient for all Teams policy governance. Any use must go through `GraphClientInterface` and `config/graph_contracts.php` in a later spec. |
| `graph_beta_experimental` | Microsoft Graph beta-only Teams resources. | `new_graph_contract` only after beta risk review | Excluded from certification/customer claims and Cohort 1 unless a later spec explicitly accepts internal-only beta capture. |
| `sharepoint_pnp_related` | Teams file governance and channel files where source truth lives in SharePoint/OneDrive. | `unsupported` for this spec; likely separate SharePoint/OneDrive/PnP strategy later | Deferred boundary. Do not present as Teams policy support. |
| `unsupported_manual_only` | Portal-only, operational, end-user content, or unsafe actions. | `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. |

## Teams 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 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| App governance | `appPermissionPolicy`, `appSetupPolicy`, `teamsAppSettings`, app-centric management state | `teams_powershell` for policies; `graph_v1` may cover app catalog/installations but not all policy state. | `new_teams_powershell_adapter` plus later Graph contracts where proven. | Collections of policy objects, plus tenant singleton settings. | Medium: policy IDs/source IDs required; display names are not enough. | High: Teams administrator/application permissions and directory roles can be broad. | Medium/high: app-centric management can supersede legacy policy meaning. | High: app lists, app IDs, and catalog metadata need safe summaries. | High value for app governance and MSP reviews. | `appPermissionPolicy` and `appSetupPolicy` are Cohort 1 selected. App-centric management is Cohort 2/unknown until source clarity improves. |
| Meetings and events | `meetingPolicy`, `meetingConfiguration`, live events/town hall policies | `teams_powershell` | `new_teams_powershell_adapter` | Collections plus possible singleton tenant settings. | Medium: policy IDs/source IDs required. | High: meeting/recording/transcription controls are sensitive. | Medium: settings vary by feature availability and license. | Critical: recordings, transcripts, chat/message content must never be captured or rendered as config evidence. | High value for collaboration risk posture. | `meetingPolicy` is Cohort 1 selected; event-specific variants are Cohort 2. |
| Messaging and channels | `messagingPolicy`, `teamsChannelsPolicy`, `teamsClientConfiguration` | `teams_powershell`; Graph teams/channels APIs are inventory surfaces, not a replacement for policy capture. | `new_teams_powershell_adapter` or later `new_graph_contract` for team/channel inventory only. | Policy collections and tenant singleton settings. | Medium. | Medium/high: communication controls affect user collaboration. | Medium: policy settings can expand over time. | High: message content, chat content, attachments, and transcripts are forbidden evidence. | High for policy posture, lower for raw channel inventory. | `messagingPolicy` and `teamsChannelsPolicy` are Cohort 1 selected; team/channel inventory is deferred. |
| Calling and voice | `voiceRoute`, `onlineVoiceRoutingPolicy`, `teamsCallingPolicy`, `callParkPolicy`, phone-number configuration | `teams_powershell` | `new_teams_powershell_adapter` | Collections and tenant-level voice configuration. | Medium/high: voice routes and policies may use composite identity. | High: licensing, PSTN, phone-number, and emergency-calling permissions can be broad. | High: tenant readiness varies by license/geography. | Medium/high: phone-number and routing data can be sensitive. | Medium/high value, but complexity is high. | `voiceRoute` and calling policies are Cohort 2, not Cohort 1. |
| External and guest access | `externalAccessPolicy`, `tenantFederationConfiguration`, `guestMeetingConfiguration`, guest/external collaboration settings | `teams_powershell` and Microsoft 365/Entra boundary references. | `new_teams_powershell_adapter`; some pieces may require Entra or cross-workload follow-up. | Singleton plus policy collections. | Medium. | High: external collaboration posture is sensitive. | Medium: some controls overlap Entra cross-tenant access or Microsoft 365 admin center settings. | Medium/high: external domains and tenant identifiers need redaction discipline. | High customer and MSP value. | `externalAccessPolicy` is Cohort 1 selected; federation/guest variants are Cohort 2. |
| Files, storage, and integration boundary | Teams channel files, cloud storage providers, tabs, connectors, app installations | `graph_v1` for Teams entities; `sharepoint_pnp_related` for files; possible app catalog Graph surfaces. | `new_graph_contract`, `unsupported`, or future SharePoint/PnP adapter. | Teams/channel/app collections; files live in SharePoint. | Medium/high: Teams group/team/channel IDs are stable but file identity belongs elsewhere. | High: file/storage permissions cross workloads. | High: SharePoint/OneDrive ownership and paging are separate domains. | Critical: file contents and message attachments are forbidden. | Medium for inventory, high for future governance, but not safe Cohort 1. | Deferred to SharePoint/OneDrive or Teams Graph inventory spec. |

## Teams Cohort Guidance

Cohort 1 should focus on tenant and policy objects that Teams PowerShell can read without touching user content, file content, chat messages, meeting recordings, transcripts, or per-user explosion paths. Microsoft Graph should be used only for Teams entities where the official Graph resource is the actual source of truth and the later implementation goes through the existing Graph client contract path.

## Forbidden Source Authority Rules

- Do not treat Teams admin center UI instructions as runtime source contracts.
- Do not capture Teams chat, message, file, recording, transcript, or meeting content as configuration evidence.
- Do not use Graph Teams APIs to imply Teams policy coverage when the policy source is Teams PowerShell.
- Do not use app-centric management or unified app management wording as a claim until a later spec proves the source and migration semantics.
- Do not execute shell commands in unit tests.
- Do not store certificates, private keys, client secrets, access tokens, raw provider responses, chat content, meeting content, file content, or transcripts 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.