@dbx-tools/teams 0.3.39

package/README.md

@@ -0,0 +1,259 @@
+# @dbx-tools/teams
+
+Server-side Microsoft Teams Adaptive Card runtime, agent tool, and AppKit
+plugin.
+
+Import this package when an AppKit or Mastra backend needs to answer like a
+Teams bot - a conversation endpoint whose replies are Adaptive Cards - or to turn
+a model's short, structured description of a status/result into a valid Teams
+Adaptive Card to render in a preview UI or post to a channel. AppKit ships no
+first-party Teams / Adaptive Card surface, so this is additive rather than an
+alternative to a native plugin. The browser-safe card schemas live in
+[`@dbx-tools/shared-teams`](../../shared/teams), and the React renderer (the
+`adaptivecards` JavaScript renderer) lives in
+[`@dbx-tools/ui-teams`](../../ui/teams).
+
+**Key features:**
+
+- AppKit plugin registration that resolves config, logs the effective card
+  version and webhook state at boot, and mounts card-build / card-post routes.
+- Two agent surfaces over one runtime: a Mastra `create_teams_card` tool and an
+  AppKit `teams.createCard` tool, both taking the small `CardSpec` vocabulary.
+- A deterministic builder that compiles a `CardSpec` (title, subtitle, text,
+  key/value facts, link actions) into a valid Adaptive Card 1.5 document, so a
+  card is well-formed by construction rather than by hoping the model produced
+  correct schema.
+- Optional posting to a Teams incoming webhook, wrapped in the attachment
+  envelope Teams expects, with a retrying execution policy.
+- `POST /api/teams/messages` - the REAL Microsoft Teams messaging endpoint: the
+  URL you paste into an Azure Bot registration so a Teams channel can chat with
+  your agents. It validates the Bot Service JWT (signature, issuer, and an
+  audience equal to your bot's app id), acknowledges immediately, and delivers
+  the agent's card back over the Bot Framework Connector API. This is the
+  Teams-shaped analogue of how the Mastra plugin exposes MCP at a path - the
+  protocol is the interface.
+- `POST /api/teams/activity` - the same turn, run SYNCHRONOUSLY with the reply
+  activities in the response body. No bot registration required, so this is what
+  a local client, a test, or any non-Teams caller uses. The conversation id maps
+  onto the agent's memory thread, so repeat turns continue one conversation.
+- `POST /api/teams/card` route a browser dev page posts to for a live card
+  preview, and `POST /api/teams/post` to push a card to the webhook.
+
+## Register The AppKit Plugin
+
+```ts
+import { createApp, server } from "@databricks/appkit";
+import { plugin as teamsPlugin, tool as teamsTool } from "@dbx-tools/teams";
+import { agents, plugin as mastraPlugin } from "@dbx-tools/appkit-mastra";
+
+const support = agents.createAgent({
+  instructions: "Summarize results as Teams cards when asked.",
+  tools: () => ({ create_teams_card: teamsTool.teamsCardTool() }),
+});
+
+await createApp({
+  plugins: [
+    server(),
+    teamsPlugin.teams({ webhookUrl: process.env.TEAMS_WEBHOOK_URL }),
+    mastraPlugin.mastra({ agents: support, storage: true }),
+  ],
+});
+```
+
+`plugin.teams()` resolves config, primes the shared runtime, logs the effective
+card version and whether a webhook is wired up, and mounts the build / post
+routes under `/api/teams`. `tool.teamsCardTool()` creates the Mastra
+`create_teams_card` tool; the AppKit `teams.createCard` tool is the same
+capability for an AppKit agent and is auto-inheritable because building a card
+has no side effects.
+
+## Converse In Cards
+
+```bash
+curl -X POST http://localhost:8000/api/teams/activity \
+  -H 'content-type: application/json' \
+  -d '{
+        "activity": {
+          "type": "message",
+          "text": "did the deploy land?",
+          "from": { "id": "user-1", "name": "Reggie" },
+          "conversation": { "id": "conv-1" }
+        }
+      }'
+```
+
+The reply is `{ "activities": [...] }`, each activity carrying
+`attachments[].contentType === "application/vnd.microsoft.card.adaptive"` with a
+compiled Adaptive Card under `content` - what a Teams client renders.
+
+A turn runs in two passes, and the order is the whole point:
+
+1. **Answer.** The agent answers the question normally - its tools available, no
+   `structuredOutput`, and nothing about cards in the prompt.
+2. **Format.** A second `structuredOutput` pass reformats that answer into a
+   `CardSpec`, which the builder compiles.
+
+Asking for the answer AND the card shape in one request makes the model treat
+formatting as the task: it emits a card immediately, never calls its tools, and a
+question that should have queried Genie comes back as "I don't have a real system
+connected - here is a template card". Answering first means this endpoint's
+CONTENT matches what the streaming chat endpoint would say; only the
+presentation differs. Agents keep `create_teams_card` for the other direction -
+answering in prose on a chat endpoint and choosing to attach a card - and when
+the agent calls it during pass 1, that spec wins and pass 2 is skipped.
+
+Because the schema is prompt-injected rather than provider-enforced (Databricks
+Model Serving rejects `response_format` alongside `tools`), the format pass is
+best-effort, so the answer is recovered in layers: the parsed spec, a full
+Adaptive Card DOCUMENT read back into the spec vocabulary (what a capable model
+often returns when asked for "an Adaptive Card"), the payload Mastra rejected off
+the thrown error, JSON embedded in prose, then the prose itself. A formatting
+miss costs structure, never the answer.
+
+Host embed markers (`[data:<id>]`, `[chart:<id>]`) are stripped from the answer:
+a chat UI swaps those for a rendered table or chart, but a card has no such slot,
+so a marker would render as literal `[data:01f1...]` where a number belongs. The
+answering pass asks the agent for the values themselves instead.
+
+The agent is resolved from the sibling Mastra plugin by registered name
+(`agentPlugin`, default `mastra`), so this package stays a leaf add-on and takes
+no dependency on `@dbx-tools/appkit-mastra`. Pass `agentId` in the body to pick a
+specific agent; omit it for the default one. An unmounted agent plugin answers
+503, an unknown `agentId` answers 404.
+
+The same lookup fetches the plugin's `createRequestContext()`, which builds the
+per-turn Mastra `RequestContext` the turn passes to both passes. This is required
+for parity with chat: user-scoped tools read the AppKit user off that context, so
+without it `ask_genie` answers "the data source is unreachable" while the chat
+routes answer with real numbers. A provider that exposes no factory still serves
+turns, just without user-scoped tools.
+
+Activities that carry no prompt - a `typing` indicator, a `conversationUpdate`
+when someone joins, an empty message - answer `{ "activities": [] }` rather than
+erroring, which is what a real bot does with them.
+
+[`@dbx-tools/ui-teams`](../../ui/teams)'s `TeamsChat` is the matching client.
+
+## Build A Card Directly
+
+```ts
+import { builder } from "@dbx-tools/teams";
+
+const { card } = builder.buildCardResult({
+  title: "Deployment succeeded",
+  subtitle: "prod • 2m ago",
+  facts: [{ title: "Version", value: "1.4.2" }],
+  actions: [{ title: "View run", url: "https://example.com/runs/42" }],
+});
+// `card` is a full Adaptive Card document; render it with @dbx-tools/ui-teams
+// or post it with the plugin's `postCard` export.
+```
+
+## Why Use This Over Native AppKit
+
+AppKit has no Teams or Adaptive Card surface at all, so use this whenever an
+agent should emit a Teams card. The value is the policy layer around a card: the
+model works in a small, safe vocabulary (`CardSpec`) instead of raw Adaptive
+Card JSON, the builder guarantees a schema-valid Adaptive Card 1.5 document, and
+posting is gated behind an explicitly configured incoming webhook. Same add-on
+shape as [`@dbx-tools/email`](../email).
+
+## Configuration
+
+Precedence per field: explicit plugin config wins, then the matching
+environment variable.
+
+- `cardVersion` / `TEAMS_CARD_VERSION` - Adaptive Card schema version the
+  builder targets. Defaults to `1.5` (what Teams supports).
+- `webhookUrl` / `TEAMS_WEBHOOK_URL` - optional Teams incoming-webhook URL. When
+  unset, posting is disabled and the plugin only builds cards for a UI to
+  render. A value that is not an absolute URL fails config resolution.
+- `agentPlugin` / `TEAMS_AGENT_PLUGIN` - registered name of the sibling plugin
+  whose agents answer a conversation turn. Defaults to `mastra`; set it when the
+  Mastra plugin is mounted under a `config.name` override.
+- `appId` / `TEAMS_APP_ID` (alias `MICROSOFT_APP_ID`) - the Entra app (client)
+  id from your Azure Bot registration. Required before `POST /messages` accepts
+  anything: it is the audience an inbound token must carry.
+- `appPassword` / `TEAMS_APP_PASSWORD` (alias `MICROSOFT_APP_PASSWORD`) - client
+  secret for that app id, used to fetch the outbound Connector token.
+- `appTenantId` / `TEAMS_APP_TENANT_ID` (alias `MICROSOFT_APP_TENANT_ID`) - set
+  only for a SINGLE-tenant bot; leave unset for multi-tenant.
+- `allowUnauthenticated` / `TEAMS_ALLOW_UNAUTHENTICATED` - serve `/messages`
+  with NO token validation, replying in the HTTP response instead of through the
+  Connector API. For local development only, and ignored unless `NODE_ENV` is
+  `development`, so a production build cannot be talked into it by an
+  environment variable. See "Connect A Real Teams Channel".
+
+The `MICROSOFT_APP_*` aliases are the names the Bot Framework SDK and the Azure
+portal already use, so an existing bot's environment drops in unchanged.
+
+## Connect A Real Teams Channel
+
+1. Create an **Azure Bot** resource and note its **Microsoft App ID**; create a
+   client secret for it.
+2. Set its **Messaging endpoint** to `https://<your-app-host>/api/teams/messages`.
+3. Enable the **Microsoft Teams** channel on the bot.
+4. Give the app `TEAMS_APP_ID` and `TEAMS_APP_PASSWORD` (plus
+   `TEAMS_APP_TENANT_ID` for a single-tenant registration).
+5. Install the bot in Teams (via a Teams app manifest referencing the same app
+   id) and message it. The agent answers in Adaptive Cards.
+
+What the endpoint does on each inbound request:
+
+- **Validates the JWT** against the Bot Framework JWKS, requiring a trusted
+  issuer and an audience equal to `appId`. The audience check is the one that
+  matters: a token the Bot Service issued for someone ELSE's bot is signed by the
+  same keys, so without it anyone with their own bot could drive your agent.
+- **Pins the reply destination to the token.** `serviceUrl` arrives in the
+  request body, and replies carry your bot's credentials, so it is honored only
+  when it matches the verified token's own `serviceurl` claim.
+- **Answers `200` before running the agent.** Bot Service times out an
+  unacknowledged activity in seconds and retries it, while a card takes longer
+  than that - so a synchronous reply would produce duplicate cards. The typing
+  indicator shows while the agent works, and the card is delivered through the
+  Connector API when it is ready.
+
+For local development without a registration, set `allowUnauthenticated: true`
+(with `NODE_ENV=development`) and `/messages` will answer in the HTTP response,
+which is how the in-repo demo renders live cards.
+
+## Routes
+
+Mounted under the plugin base path `/api/teams`:
+
+- `POST /messages` - the Teams messaging endpoint (see above). Body is a bare Bot
+  Framework activity. `401` on a token that fails validation, `503` when no
+  `appId`/`appPassword` is configured, `400` on an invalid activity or a
+  `serviceUrl` that does not match the token. Answers `200` with an empty body;
+  the reply arrives over the Connector API.
+- `POST /activity` - run one conversation turn. Body is
+  `{ activity, agentId?, model? }`; the response is `{ activities }`, each
+  carrying Adaptive Card attachments. `400` on an invalid activity, `404` on an
+  unknown `agentId`, `503` when no agent plugin is registered.
+- `POST /card` - compile a `CardSpec` request body into an Adaptive Card
+  document. The dev display page posts here to preview cards live.
+- `POST /post` - compile then push a `CardSpec` to the configured Teams
+  incoming webhook; a `400` when the body is invalid, an error when no webhook
+  is configured.
+
+## Modules
+
+- `plugin` - `teams` (the plugin factory) and `TeamsPlugin`.
+- `tool` - `teamsCardTool` and `CREATE_CARD_DESCRIPTION`.
+- `builder` - `buildAdaptiveCard` / `buildCardResult` (pure `CardSpec` -> card
+  compilation).
+- `conversation` - `runCardTurn` (one activity in, card activities out),
+  `resolveCardAgent`, `promptOf`, `toReplyActivity`, `CARD_TURN_INSTRUCTIONS`,
+  and the `CardAgentLike` / `AgentProviderLike` shapes.
+- `auth` - `verifyBotToken` (inbound Bot Service JWT validation),
+  `connectorToken` (outbound client-credentials token), `isAllowedServiceUrl`,
+  and `resetTeamsAuth`.
+- `connector` - `sendActivity` / `sendTyping`, the Bot Framework Connector API
+  calls a reply is delivered through.
+- `messaging` - `deliverTurn` (acknowledge-then-deliver turn) and
+  `resolveServiceUrl`.
+- `runtime` - `getTeamsRuntime`, `setTeamsExecutor`, `buildCard`, `postCard`,
+  and the `TeamsExecutor` / `TeamsRuntime` types.
+- `config` - `resolveTeamsConfig`, `TEAMS_CONFIG_SCHEMA`, the env-name
+  constants, and the `TeamsPluginConfig` / `ResolvedTeamsConfig` types.
+- `defaults` - the interceptor execution settings and named caps.

package/index.ts

@@ -0,0 +1,22 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as auth from "./src/auth";
+export * as builder from "./src/builder";
+export * as config from "./src/config";
+export * as connector from "./src/connector";
+export * as conversation from "./src/conversation";
+export * as defaults from "./src/defaults";
+export * as messaging from "./src/messaging";
+export * as plugin from "./src/plugin";
+export * as runtime from "./src/runtime";
+export * as tool from "./src/tool";
+export type { VerifiedBotToken, VerifyOptions } from "./src/auth";
+export type { TeamsPluginConfig, ResolvedTeamsConfig } from "./src/config";
+export type { ConnectorTarget } from "./src/connector";
+export type { CardAgentLike, AgentResult, AgentProviderLike, CardTurnOptions, CardContextFactory } from "./src/conversation";
+export type { TeamsExecuteConfig, TeamsExecutionSettings } from "./src/defaults";
+export type { BotCredentials, DeliverTurnOptions } from "./src/messaging";
+export type { TeamsExecutor, TeamsRuntime } from "./src/runtime";
+export type { TeamsCardToolOptions } from "./src/tool";

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@dbx-tools/teams",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/node/teams"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.5",
+    "@types/json-schema": "^7",
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@databricks/appkit": "^0.43.0",
+    "@mastra/core": "^1.47.0",
+    "jose": "^6.2.3",
+    "zod": "4.3.6",
+    "@dbx-tools/shared-core": "0.3.39",
+    "@dbx-tools/shared-teams": "0.3.39"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.3.39",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "dbxToolsConfig": {
+    "tags": [
+      "node"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,294 @@
+/**
+ * Inbound and outbound authentication for the Teams messaging endpoint.
+ *
+ * `POST /api/teams/messages` is a PUBLIC URL - Azure Bot Service calls it from
+ * the internet, so it cannot sit behind AppKit's OBO headers or a workspace
+ * login. Its only trust boundary is the JWT the Bot Service signs each request
+ * with, which is what this module verifies:
+ *
+ *   1. fetch the Bot Framework OpenID metadata to discover the signing JWKS;
+ *   2. verify the token's signature against that key set;
+ *   3. check `issuer` is a known Bot Service issuer and `audience` is exactly
+ *      this bot's app id.
+ *
+ * All three matter. Skipping (3) is the classic bot vulnerability: a token the
+ * Bot Service legitimately issued for a DIFFERENT bot still verifies against the
+ * same JWKS, so without an audience check anyone with their own bot could drive
+ * this agent.
+ *
+ * The outbound half is the reverse: replies go to the Connector API, which needs
+ * a client-credentials token for the bot's own app registration. Both key sets
+ * and tokens are cached, since a busy channel would otherwise re-fetch metadata
+ * on every turn.
+ *
+ * @module
+ */
+
+import { error, log } from "@dbx-tools/shared-core";
+import { createRemoteJWKSet, jwtVerify, type JWTPayload } from "jose";
+
+/**
+ * OpenID metadata document for tokens the Bot Service sends a bot in the public
+ * cloud. The JWKS URI is read from this document rather than hard-coded so a key
+ * rotation on Microsoft's side needs no release here.
+ *
+ * Overridable per call ({@link VerifyOptions.metadataUrl}) because a sovereign
+ * cloud (GCC High / DoD) publishes its own metadata endpoint - and because it
+ * makes the verifier testable against a local key set.
+ */
+export const BOT_OPENID_METADATA =
+  "https://login.botframework.com/v1/.well-known/openidconfiguration";
+
+/**
+ * Accepted `iss` values on an inbound token.
+ *
+ * The Bot Service has issued tokens under several issuers across channel and
+ * tenant configurations, and a single-tenant bot receives the v2 Entra issuer
+ * with its own tenant id spliced in (handled by {@link isTrustedIssuer}). The
+ * fixed set covers the channel-issued cases.
+ */
+const TRUSTED_ISSUERS = [
+  "https://api.botframework.com",
+  "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
+  "https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0",
+] as const;
+
+/** Token endpoint issuing the Connector credentials an outbound reply uses. */
+const LOGIN_TOKEN_URL = (tenant: string) =>
+  `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/token`;
+
+/**
+ * Scope requested for a Connector token. `.default` asks for the app's
+ * statically configured permissions, which is what a bot registration grants.
+ */
+const CONNECTOR_SCOPE = "https://api.botframework.com/.default";
+
+/** Tenant used for a multi-tenant bot, which has no tenant of its own. */
+const MULTI_TENANT = "botframework.com";
+
+/**
+ * Refresh an access token this many milliseconds BEFORE it actually expires, so
+ * a token never expires mid-flight between the check and the Connector call.
+ */
+const TOKEN_SKEW_MS = 60_000;
+
+const logger = log.logger("teams:auth");
+
+/**
+ * Lazily-created, cached remote key set. `createRemoteJWKSet` handles its own
+ * key caching and rotation (re-fetching only on an unknown `kid`), so this is
+ * created once per process rather than per request.
+ */
+let keySet: ReturnType<typeof createRemoteJWKSet> | undefined;
+
+/** Cached JWKS URI discovered from the OpenID metadata document, keyed by metadata URL. */
+let jwksUri: string | undefined;
+
+/** Metadata URL the cached key set was built from, so an override busts the cache. */
+let keySetSource: string | undefined;
+
+/** Reset cached auth state. Test seam; not part of the public contract. */
+export const resetTeamsAuth = (): void => {
+  keySet = undefined;
+  jwksUri = undefined;
+  keySetSource = undefined;
+  tokenCache = undefined;
+};
+
+/**
+ * Discover the signing JWKS URI from the Bot Framework OpenID metadata.
+ *
+ * Cached for the life of the process: it is a stable pointer, and the key
+ * rotation that actually matters happens inside the key set it names.
+ */
+const discoverJwksUri = async (metadataUrl: string, signal?: AbortSignal): Promise<string> => {
+  if (jwksUri && keySetSource === metadataUrl) return jwksUri;
+  const response = await fetch(metadataUrl, { ...(signal ? { signal } : {}) });
+  if (!response.ok) {
+    throw new Error(`teams: could not fetch Bot Framework OpenID metadata (${response.status})`);
+  }
+  const metadata = (await response.json()) as { jwks_uri?: unknown };
+  const uri = typeof metadata.jwks_uri === "string" ? metadata.jwks_uri : null;
+  if (!uri) throw new Error("teams: Bot Framework OpenID metadata carried no jwks_uri");
+  jwksUri = uri;
+  keySetSource = metadataUrl;
+  return uri;
+};
+
+/** The key set for the discovered JWKS URI, created once and reused. */
+const signingKeys = async (
+  metadataUrl: string,
+  signal?: AbortSignal,
+): Promise<ReturnType<typeof createRemoteJWKSet>> => {
+  if (keySet && keySetSource === metadataUrl) return keySet;
+  const uri = await discoverJwksUri(metadataUrl, signal);
+  keySet = createRemoteJWKSet(new URL(uri));
+  return keySet;
+};
+
+/**
+ * Whether `issuer` is one this bot accepts.
+ *
+ * A single-tenant bot receives tokens issued by its OWN tenant, so the
+ * configured tenant's v2 issuer is accepted in addition to the fixed channel
+ * issuers.
+ */
+const isTrustedIssuer = (issuer: string | undefined, tenantId?: string): boolean => {
+  if (!issuer) return false;
+  if ((TRUSTED_ISSUERS as readonly string[]).includes(issuer)) return true;
+  if (!tenantId) return false;
+  return (
+    issuer === `https://login.microsoftonline.com/${tenantId}/v2.0` ||
+    issuer === `https://sts.windows.net/${tenantId}/`
+  );
+};
+
+/** A verified inbound Bot Framework token. */
+export interface VerifiedBotToken {
+  /** The token's claims, after signature / issuer / audience validation. */
+  claims: JWTPayload;
+  /**
+   * The `serviceUrl` the token was issued for, when it carries one. Bot Service
+   * tokens include this claim; comparing it to the activity's `serviceUrl` is
+   * what stops a valid token being replayed to redirect replies elsewhere.
+   */
+  serviceUrl?: string;
+}
+
+/** Options for {@link verifyBotToken}. */
+export interface VerifyOptions {
+  /** The bot's app id; the ONLY audience an inbound token may carry. */
+  appId: string;
+  /** Tenant of a single-tenant bot, whose own issuer is then also accepted. */
+  appTenantId?: string;
+  /**
+   * OpenID metadata document naming the signing key set. Defaults to
+   * {@link BOT_OPENID_METADATA}; override for a sovereign cloud.
+   */
+  metadataUrl?: string;
+  /** Cancels the metadata / JWKS fetch with the request. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Verify the `Authorization` header on an inbound Bot Service request.
+ *
+ * Rejects (by throwing) a missing / malformed header, a bad signature, an
+ * untrusted issuer, or an audience that is not this bot's `appId`. The caller
+ * turns a throw into a 401 - never into a processed activity.
+ */
+export const verifyBotToken = async (
+  authorization: string | undefined,
+  options: VerifyOptions,
+): Promise<VerifiedBotToken> => {
+  const token = bearerToken(authorization);
+  if (!token) throw new Error("teams: request carried no bearer token");
+
+  const keys = await signingKeys(options.metadataUrl ?? BOT_OPENID_METADATA, options.signal);
+  // `audience` is enforced by the verifier itself: a token the Bot Service
+  // issued for someone else's bot verifies against this same JWKS, so the
+  // audience check - not the signature - is what binds a request to THIS bot.
+  const { payload } = await jwtVerify(token, keys, { audience: options.appId });
+
+  if (!isTrustedIssuer(payload.iss, options.appTenantId)) {
+    throw new Error(`teams: untrusted token issuer '${payload.iss ?? "none"}'`);
+  }
+
+  const serviceUrl = typeof payload.serviceurl === "string" ? payload.serviceurl : undefined;
+  return { claims: payload, ...(serviceUrl ? { serviceUrl } : {}) };
+};
+
+/** Read the bearer value out of an `Authorization` header. */
+const bearerToken = (authorization: string | undefined): string | null => {
+  if (!authorization) return null;
+  const [scheme, value] = authorization.split(/\s+/, 2);
+  if (!value || scheme?.toLowerCase() !== "bearer") return null;
+  return value.trim() || null;
+};
+
+/** A cached Connector access token and the moment it stops being usable. */
+interface CachedToken {
+  token: string;
+  expiresAt: number;
+}
+
+let tokenCache: CachedToken | undefined;
+
+/**
+ * Fetch (or reuse) a Connector API access token for the bot's own app
+ * registration.
+ *
+ * Cached until shortly before expiry: a Connector token is valid for ~1h, and
+ * re-fetching per reply would add a round trip to every turn.
+ */
+export const connectorToken = async (options: {
+  appId: string;
+  appPassword: string;
+  appTenantId?: string;
+  signal?: AbortSignal;
+}): Promise<string> => {
+  const now = Date.now();
+  if (tokenCache && tokenCache.expiresAt > now) return tokenCache.token;
+
+  const body = new URLSearchParams({
+    grant_type: "client_credentials",
+    client_id: options.appId,
+    client_secret: options.appPassword,
+    scope: CONNECTOR_SCOPE,
+  });
+  const response = await fetch(LOGIN_TOKEN_URL(options.appTenantId ?? MULTI_TENANT), {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body,
+    ...(options.signal ? { signal: options.signal } : {}),
+  });
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(
+      `teams: could not obtain a Connector token (${response.status}) ${detail}`.trim(),
+    );
+  }
+  const payload = (await response.json()) as { access_token?: unknown; expires_in?: unknown };
+  const token = typeof payload.access_token === "string" ? payload.access_token : null;
+  if (!token) throw new Error("teams: token response carried no access_token");
+  const expiresIn = typeof payload.expires_in === "number" ? payload.expires_in : 3600;
+  tokenCache = { token, expiresAt: now + expiresIn * 1000 - TOKEN_SKEW_MS };
+  logger.debug("connector token refreshed", { expiresIn });
+  return token;
+};
+
+/**
+ * Host suffixes replies may be sent to when the token pins no `serviceUrl`.
+ *
+ * `smba.trafficmanager.net` is the one that matters in practice: that is where
+ * Teams itself serves the Connector API from (per-region, e.g.
+ * `https://smba.trafficmanager.net/amer/`), so omitting it would reject every
+ * real Teams reply. Compared as dot-prefixed suffixes (or exact matches) so a
+ * lookalike host like `botframework.com.attacker.example` cannot pass.
+ */
+const ALLOWED_SERVICE_HOSTS = ["botframework.com", "trafficmanager.net", "microsoft.com"] as const;
+
+/**
+ * Whether `serviceUrl` is one replies may be sent to.
+ *
+ * Only ever the host the verified token was issued for. A Bot Service token is a
+ * bearer credential, so honoring the `serviceUrl` from the request BODY would
+ * let a replayed token point the bot's authenticated replies (and its token) at
+ * an attacker-controlled host. When the token carries no `serviceurl` claim the
+ * body value is accepted but restricted to Microsoft's own domains.
+ */
+export const isAllowedServiceUrl = (serviceUrl: string, tokenServiceUrl?: string): boolean => {
+  const normalize = (value: string) => value.replace(/\/+$/, "").toLowerCase();
+  if (tokenServiceUrl) return normalize(serviceUrl) === normalize(tokenServiceUrl);
+  try {
+    const { protocol, hostname } = new URL(serviceUrl);
+    if (protocol !== "https:") return false;
+    const host = hostname.toLowerCase();
+    return ALLOWED_SERVICE_HOSTS.some(
+      (allowed) => host === allowed || host.endsWith(`.${allowed}`),
+    );
+  } catch (err) {
+    logger.debug("rejecting unparseable serviceUrl", { error: error.errorMessage(err) });
+    return false;
+  }
+};