ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
0e2cea30bb
TenantAtlas/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-source-surface-catalog.md
ahmido 0e2cea30bb spec: add Exchange Teams source-surface catalog adapter strategy (#496) 
Automated giteaflow PR from branch 429-exchange-teams-source-surface-catalog-adapter-strategy.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #496
2026-07-04 20:59:58 +00:00

12 KiB
Raw Blame History

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:

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.