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
• Connect-MicrosoftTeams
• Application-based authentication in Teams PowerShell Module
• Use app permission policies to control user access to apps
• Use setup policies to manage, install and pin agents and apps for users
• Teams settings and policies reference
• Use guest access and external access to collaborate with people outside your organization
• Use the Microsoft Graph API to work with Microsoft Teams

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.