Docs: Service URL validation and DevTools production guard

teams.md/docs/main/developer-tools/devtools/README.md

@@ -18,3 +18,15 @@ preventing you from needing to deploy/register the app or expose a public endpoi
 - **Cards**: Use the Cards page to visually design and test your cards.
 
 Continue on to the next pages to learn more about the features available in DevTools.
+
+## Production environments
+
+:::warning
+DevTools is designed for local development only. It will **not start** in production environments. The following environment checks are enforced:
+
+- **TypeScript**: `NODE_ENV=production`
+- **Python**: `PYTHON_ENV=production` or `NODE_ENV=production`
+- **C#**: `ASPNETCORE_ENVIRONMENT=Production` (via `IHostEnvironment.IsProduction()`)
+
+If your app fails to start with an error about DevTools in production, remove the DevTools plugin from your app configuration.
+:::

teams.md/src/components/include/essentials/service-url-validation/csharp.incl.md

@@ -0,0 +1,27 @@
+<!-- adding-custom-domains -->
+
+```csharp
+var app = new App(new AppOptions
+{
+    AdditionalAllowedDomains = [".my-custom-channel.com"],
+});
+```
+
+Or via `appsettings.json`:
+
+```json
+{
+  "Teams": {
+    "AdditionalAllowedDomains": [".my-custom-channel.com"]
+  }
+}
+```
+
+<!-- disabling-validation -->
+
+```csharp
+var app = new App(new AppOptions
+{
+    AdditionalAllowedDomains = ["*"],
+});
+```

teams.md/src/components/include/essentials/service-url-validation/python.incl.md

@@ -0,0 +1,15 @@
+<!-- adding-custom-domains -->
+
+```python
+app = App(
+    additional_allowed_domains=[".my-custom-channel.com"],
+)
+```
+
+<!-- disabling-validation -->
+
+```python
+app = App(
+    additional_allowed_domains=["*"],
+)
+```

teams.md/src/components/include/essentials/service-url-validation/typescript.incl.md

@@ -0,0 +1,15 @@
+<!-- adding-custom-domains -->
+
+```typescript
+const app = new App({
+  additionalAllowedDomains: ['.my-custom-channel.com'],
+});
+```
+
+<!-- disabling-validation -->
+
+```typescript
+const app = new App({
+  additionalAllowedDomains: ['*'],
+});
+```

teams.md/src/pages/templates/essentials/service-url-validation.mdx

@@ -0,0 +1,58 @@
+---
+sidebar_position: 6
+title: Service URL Validation
+summary: How the Teams SDK validates service URLs to prevent outbound requests to unauthorized endpoints
+languages: ['typescript','python','csharp']
+---
+
+# Service URL Validation
+
+The Teams SDK validates that incoming `serviceUrl` values belong to known domains before using them for outbound API calls. This prevents the bot's credentials from being sent to unauthorized endpoints.
+
+## How it works
+
+When your bot receives an activity from the Bot Framework Channel Service, the activity includes a `serviceUrl` field that tells the SDK where to send responses. The SDK validates this URL against allowed hostnames from the configured cloud environment before making any outbound requests.
+
+### Allowed hostnames by cloud
+
+Each cloud environment preset includes the allowed service URL hostnames for that cloud:
+
+| Cloud | Allowed hostnames |
+|---|---|
+| Public (default) | `smba.trafficmanager.net`, `smba.onyx.prod.teams.trafficmanager.net`, `smba.infra.gcc.teams.microsoft.com` |
+| US Gov (GCCH) | `smba.infra.gov.teams.microsoft.us` |
+| US Gov DoD | `smba.infra.dod.teams.microsoft.us` |
+| China (21Vianet) | `frontend.botapi.msg.infra.teams.microsoftonline.cn` |
+| `localhost` / `127.0.0.1` | Always allowed for local development |
+
+If your bot is configured for a sovereign cloud, only that cloud's hostnames are allowed by default.
+
+## Adding custom domains
+
+If your bot receives activities from a service URL outside the cloud preset's allowlist (e.g., sovereign clouds without presets, non-Teams channels, or custom environments), you can add additional domains.
+
+Sovereign cloud FQDNs that require `additionalAllowedDomains`:
+
+| Environment | FQDN |
+|---|---|
+| France (Bleu) | `smba.teams.sovcloud-core.fr` |
+| EagleX | `frontend.botapi.msg.infra.teams.eaglex.ic.gov` |
+| SCloud | `frontend.botapi.msg.infra.teams.microsoft.scloud` |
+
+<LanguageInclude section="adding-custom-domains" />
+
+## Disabling validation
+
+:::warning
+Disabling service URL validation removes a security protection that prevents your bot's credentials from being sent to unauthorized endpoints. Only disable this if you understand the security implications.
+:::
+
+If you have a non-standard setup where domain-based validation does not work, you can disable it by passing `*` as an additional domain:
+
+<LanguageInclude section="disabling-validation" />
+
+## Proactive messaging
+
+:::info
+Service URL validation runs on incoming activities. If you store a `ConversationReference` for proactive messaging, the `serviceUrl` was validated when the original activity was received. Only store conversation references from validated inbound activities -- never from untrusted external sources.
+:::