feat(teams): format primitive subpath (chat@4.31 8c71411)

Port the NET-NEW upstream packages/adapter-teams/src/format/index.ts
helpers as a low-level, runtime-free string-primitive module at
src/chat_sdk/adapters/teams/format.py — distinct from the existing
AST-based format_converter.py.

Helpers: escape_teams_text / unescape_teams_text, format_teams_mention,
teams_mention_to_plain_text, teams_html_to_markdown, markdown_to_teams_html,
convert_teams_emoji_placeholders, safe_link_href.

- SDK-free: plain strings + stdlib only (re, urllib.parse); no
  microsoft_teams.* and no adapter/runtime imports. Mirrors the Slack
  primitive subpath layout and lazy-import style.
- markdown_to_teams_html gates link hrefs through an exact
  {http, https, mailto} protocol allowlist via urllib.parse.urlparse
  (port of the upstream URL().protocol check) — rejects javascript:,
  data:, relative, and other unsafe hrefs (SSRF / injection guard).
- escape_teams_text runs before any tag insertion so a user-supplied
  '<' cannot forge HTML (emit/parse symmetry).
- Emoji placeholders reuse chat_sdk.emoji (no duplicated emoji map):
  each upstream colon placeholder maps to a normalized SDK emoji name
  and delegates the unicode lookup to convert_emoji_placeholders.

Tests (tests/test_teams_format_primitives.py): the 6 upstream
index.test.ts cases + a source-level import-boundary test (faithful port
of format/boundary.test.ts) + adversarial forged-tag and
disallowed-protocol cases. 14 tests, all green.

Lane-scoped: only the new module + its test file; no shared files
touched (lazy subpath registration in teams/__init__.py deferred to the
packaging PR).

Author: patrick-chinchill

src/chat_sdk/adapters/teams/format.py

@@ -0,0 +1,186 @@
+"""Teams format primitives — a lightweight, runtime-free subpath.
+
+Port of ``packages/adapter-teams/src/format/index.ts`` (vercel/chat@4.31,
+commit 8c71411), exposed upstream as ``@chat-adapter/teams/format``. Provides
+runtime-free primitives for escaping/unescaping Teams text, building and
+normalizing ``<at>`` mentions, and converting between Teams' restricted HTML
+subset and Markdown-ish text — without the full Teams adapter, the
+``microsoft_teams`` SDK, or the chat runtime.
+
+This is intentionally distinct from :mod:`chat_sdk.adapters.teams.format_converter`,
+which is a higher-level AST-based converter. The helpers here are low-level
+string primitives that operate purely on text.
+
+Importing this module never imports the ``microsoft_teams`` SDK, an HTTP
+client, or the high-level :mod:`chat_sdk.adapters.teams.adapter` module. Emoji
+placeholder conversion delegates to :mod:`chat_sdk.emoji` so the emoji map is
+never duplicated here.
+
+Python-specific hardening (divergence from upstream, see
+``docs/UPSTREAM_SYNC.md``): :func:`markdown_to_teams_html` gates link hrefs
+through an exact ``{http, https, mailto}`` protocol allowlist using
+:func:`urllib.parse.urlparse` (port of the upstream ``URL().protocol`` check),
+rejecting ``javascript:``, ``data:``, relative, and other unsafe hrefs so they
+render as plain text rather than active links (SSRF / injection guard).
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urlparse
+
+from chat_sdk.emoji import convert_emoji_placeholders
+
+__all__ = [
+    "convert_teams_emoji_placeholders",
+    "escape_teams_text",
+    "format_teams_mention",
+    "markdown_to_teams_html",
+    "safe_link_href",
+    "teams_html_to_markdown",
+    "teams_mention_to_plain_text",
+    "unescape_teams_text",
+]
+
+# JS source patterns ported 1:1. The `gis` flags become DOTALL | IGNORECASE in
+# Python; JS `g` (replace-all) is the default for `re.sub`/`str.replace`.
+_HTML_ESCAPE_PATTERN = re.compile(r"[&<>\"]")
+_MARKDOWN_LINK_PATTERN = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+_TEAMS_MENTION_PATTERN = re.compile(r"<at\b[^>]*>(.*?)</at>", re.DOTALL | re.IGNORECASE)
+_TAG_PATTERN = re.compile(r"<[^>]+>")
+
+# Order matters: `&` is escaped via the single-pass regex below so an already
+# present `&` is not double-escaped. Matches upstream `HTML_ESCAPES`.
+_HTML_ESCAPES: dict[str, str] = {
+    '"': "&quot;",
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+}
+
+# Upstream `EMOJI_PLACEHOLDERS` maps Slack-style colon placeholders to unicode.
+# Rather than re-declare the unicode (which would duplicate the emoji map), we
+# map each upstream placeholder to its normalized name in :mod:`chat_sdk.emoji`
+# and delegate the unicode lookup to that single source of truth.
+_PLACEHOLDER_TO_NORMALIZED: dict[str, str] = {
+    ":red_circle:": "red_circle",
+    ":warning:": "warning",
+    ":white_check_mark:": "check",
+    ":x:": "x",
+}
+
+# Exact protocol allowlist for Markdown link hrefs (port of upstream
+# `SAFE_LINK_PROTOCOLS`). `urlparse` lowercases the scheme and yields it
+# without the trailing colon, so these are bare scheme names.
+_SAFE_LINK_PROTOCOLS: frozenset[str] = frozenset({"http", "https", "mailto"})
+
+
+def escape_teams_text(text: str) -> str:
+    """Escape the Teams HTML control characters (``&``, ``<``, ``>``, ``"``).
+
+    Run this before inserting any HTML tags so user-supplied ``<`` cannot
+    forge markup.
+    """
+    return _HTML_ESCAPE_PATTERN.sub(lambda m: _HTML_ESCAPES.get(m.group(0), m.group(0)), text)
+
+
+def unescape_teams_text(text: str) -> str:
+    """Reverse :func:`escape_teams_text`.
+
+    Entities are replaced in reverse order (``&amp;`` last) so a literal
+    ``&amp;lt;`` does not collapse into ``<``.
+    """
+    return text.replace("&quot;", '"').replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&")
+
+
+def format_teams_mention(name: str) -> str:
+    """Wrap a display name in an escaped Teams ``<at>`` mention tag."""
+    return f"<at>{escape_teams_text(name)}</at>"
+
+
+def teams_mention_to_plain_text(text: str) -> str:
+    """Replace Teams ``<at>...</at>`` mention tags with ``@name`` plain text."""
+
+    def _replace(match: re.Match[str]) -> str:
+        name = match.group(1)
+        return f"@{unescape_teams_text(_strip_tags(name).strip())}"
+
+    return _TEAMS_MENTION_PATTERN.sub(_replace, text)
+
+
+def teams_html_to_markdown(html: str) -> str:
+    """Convert Teams' restricted HTML subset to Markdown-ish text."""
+    text = teams_mention_to_plain_text(html)
+    text = re.sub(r"<strong\b[^>]*>(.*?)</strong>", r"**\1**", text, flags=re.DOTALL | re.IGNORECASE)
+    text = re.sub(r"<b\b[^>]*>(.*?)</b>", r"**\1**", text, flags=re.DOTALL | re.IGNORECASE)
+    text = re.sub(r"<em\b[^>]*>(.*?)</em>", r"_\1_", text, flags=re.DOTALL | re.IGNORECASE)
+    text = re.sub(r"<i\b[^>]*>(.*?)</i>", r"_\1_", text, flags=re.DOTALL | re.IGNORECASE)
+    text = re.sub(r"<s\b[^>]*>(.*?)</s>", r"~~\1~~", text, flags=re.DOTALL | re.IGNORECASE)
+    text = re.sub(r"<strike\b[^>]*>(.*?)</strike>", r"~~\1~~", text, flags=re.DOTALL | re.IGNORECASE)
+    text = re.sub(r"<code\b[^>]*>(.*?)</code>", r"`\1`", text, flags=re.DOTALL | re.IGNORECASE)
+    text = re.sub(
+        r"<a\b[^>]*href=[\"']([^\"']+)[\"'][^>]*>(.*?)</a>",
+        r"[\2](\1)",
+        text,
+        flags=re.DOTALL | re.IGNORECASE,
+    )
+    text = re.sub(r"<br\s*/?>", "\n", text, flags=re.IGNORECASE)
+    text = re.sub(r"</p>\s*<p[^>]*>", "\n\n", text, flags=re.IGNORECASE)
+    text = _TAG_PATTERN.sub("", text)
+    text = text.replace(" ", " ")
+    return unescape_teams_text(text).strip()
+
+
+def markdown_to_teams_html(markdown: str) -> str:
+    """Convert Markdown-ish text to Teams' restricted HTML subset.
+
+    The input is escaped *before* any tag insertion so user-supplied ``<``
+    cannot forge HTML. Link hrefs are gated through :func:`safe_link_href`;
+    unsafe hrefs render as plain label text.
+    """
+    text = convert_teams_emoji_placeholders(escape_teams_text(markdown))
+    text = re.sub(r"\*\*(.*?)\*\*", r"<strong>\1</strong>", text)
+    text = re.sub(r"_(.*?)_", r"<em>\1</em>", text)
+    text = re.sub(r"~~(.*?)~~", r"<s>\1</s>", text)
+    text = re.sub(r"`([^`]+)`", r"<code>\1</code>", text)
+
+    def _link(match: re.Match[str]) -> str:
+        label, href = match.group(1), match.group(2)
+        return f'<a href="{href}">{label}</a>' if safe_link_href(href) else label
+
+    text = _MARKDOWN_LINK_PATTERN.sub(_link, text)
+    return text.replace("\n", "<br>")
+
+
+def convert_teams_emoji_placeholders(text: str) -> str:
+    """Convert Teams' Slack-style colon emoji placeholders to unicode.
+
+    Delegates the unicode lookup to :mod:`chat_sdk.emoji` so the emoji map is
+    never duplicated. Each upstream placeholder (``:white_check_mark:`` etc.)
+    is mapped to its normalized SDK emoji name and resolved to the platform
+    (unicode) form via :func:`chat_sdk.emoji.convert_emoji_placeholders`.
+    """
+    converted = text
+    for placeholder, normalized in _PLACEHOLDER_TO_NORMALIZED.items():
+        converted = converted.replace(
+            placeholder,
+            convert_emoji_placeholders(f"{{{{emoji:{normalized}}}}}", "teams"),
+        )
+    return converted
+
+
+def _strip_tags(text: str) -> str:
+    return _TAG_PATTERN.sub("", text)
+
+
+def safe_link_href(href: str) -> bool:
+    """Return ``True`` only for ``http``/``https``/``mailto`` hrefs.
+
+    Port of the upstream ``safeLinkHref`` protocol check using
+    :func:`urllib.parse.urlparse`. Rejects ``javascript:``, ``data:``,
+    relative, and any other scheme (SSRF / injection guard).
+    """
+    try:
+        return urlparse(href).scheme in _SAFE_LINK_PROTOCOLS
+    except ValueError:
+        return False

tests/test_teams_format_primitives.py

@@ -0,0 +1,150 @@
+"""Tests for the Teams format primitives subpath.
+
+Port of ``packages/adapter-teams/src/format/index.test.ts`` and
+``format/boundary.test.ts`` (vercel/chat@4.31, commit 8c71411).
+
+Distinct from ``test_teams_format.py``, which covers the higher-level
+AST-based ``TeamsFormatConverter``; this file covers the low-level
+``chat_sdk.adapters.teams.format`` string primitives and mirrors the Slack
+primitive test layout (``test_slack_format_primitives.py``).
+
+Adversarial cases (per docs/SELF_REVIEW.md) extend the upstream suite with
+forged-tag escaping and the disallowed-protocol SSRF gate.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+from chat_sdk.adapters.teams.format import (
+    convert_teams_emoji_placeholders,
+    escape_teams_text,
+    format_teams_mention,
+    markdown_to_teams_html,
+    safe_link_href,
+    teams_html_to_markdown,
+    teams_mention_to_plain_text,
+    unescape_teams_text,
+)
+
+
+class TestTeamsFormatPrimitives:
+    """Direct ports of the upstream ``Teams format primitives`` suite."""
+
+    def test_escapes_and_unescapes_teams_text(self):
+        escaped = escape_teams_text('<hello & "world">')
+        assert escaped == "&lt;hello &amp; &quot;world&quot;&gt;"
+        assert unescape_teams_text(escaped) == '<hello & "world">'
+
+    def test_formats_and_normalizes_mentions(self):
+        assert format_teams_mention("Ada & Ben") == "<at>Ada &amp; Ben</at>"
+        assert teams_mention_to_plain_text("<at>Ada &amp; Ben</at> hi") == "@Ada & Ben hi"
+
+    def test_converts_teams_html_to_markdown_ish_text(self):
+        assert (
+            teams_html_to_markdown('<p>Hello <strong>world</strong><br><a href="https://example.com">link</a></p>')
+            == "Hello **world**\n[link](https://example.com)"
+        )
+
+    def test_converts_markdown_ish_text_to_teams_html(self):
+        assert (
+            markdown_to_teams_html("**Ship** [now](https://example.com)")
+            == '<strong>Ship</strong> <a href="https://example.com">now</a>'
+        )
+        assert markdown_to_teams_html("[email](mailto:ada@example.com)") == '<a href="mailto:ada@example.com">email</a>'
+
+    def test_renders_unsafe_markdown_links_as_plain_text(self):
+        assert markdown_to_teams_html("[bad](javascript:alert)") == "bad"
+        assert markdown_to_teams_html("[relative](/internal)") == "relative"
+
+    def test_converts_common_emoji_placeholders(self):
+        assert convert_teams_emoji_placeholders(":white_check_mark: done") == "✅ done"
+
+
+class TestTeamsFormatAdversarial:
+    """Adversarial escape / SSRF cases beyond the upstream suite."""
+
+    def test_escape_runs_before_tag_insertion_so_forged_tags_are_inert(self):
+        # User-supplied `<` must be escaped before any tag insertion, so a raw
+        # `<script>` cannot survive as live markup (emit/parse symmetry).
+        assert markdown_to_teams_html("<script>alert(1)</script>") == ("&lt;script&gt;alert(1)&lt;/script&gt;")
+
+    def test_forged_anchor_in_label_does_not_emit_live_link(self):
+        # A `<` inside the markdown link label is escaped first, so the only
+        # anchor emitted is the real, protocol-gated one.
+        out = markdown_to_teams_html("[<b>x</b>](https://ok.com)")
+        assert out == '<a href="https://ok.com">&lt;b&gt;x&lt;/b&gt;</a>'
+
+    def test_disallowed_protocols_are_rejected_by_the_ssrf_gate(self):
+        # Paren-free hrefs (the upstream MARKDOWN_LINK_PATTERN href group is
+        # `[^)]+`, so an inner `)` is outside the link grammar by design).
+        for href in (
+            "javascript:alert",
+            "data:text/html,evil",
+            "vbscript:msgbox",
+            "file:///etc/passwd",
+            "/relative",
+            "ftp://example.com/x",
+        ):
+            assert markdown_to_teams_html(f"[label]({href})") == "label", href
+
+    def test_allowed_protocols_pass_the_ssrf_gate(self):
+        assert safe_link_href("http://example.com") is True
+        assert safe_link_href("https://example.com") is True
+        assert safe_link_href("mailto:ada@example.com") is True
+        # urlparse lowercases the scheme, so the gate is case-insensitive.
+        assert safe_link_href("HTTPS://EXAMPLE.COM") is True
+
+    def test_disallowed_protocols_fail_the_ssrf_gate(self):
+        assert safe_link_href("javascript:alert(1)") is False
+        assert safe_link_href("data:text/html,x") is False
+        assert safe_link_href("/internal") is False
+        assert safe_link_href("") is False
+
+    def test_unescape_does_not_collapse_double_escaped_ampersand(self):
+        # `&amp;lt;` must round-trip to `&lt;`, not `<` (reverse-order unescape).
+        assert unescape_teams_text("&amp;lt;") == "&lt;"
+
+
+def _format_module_source() -> str:
+    spec = importlib.util.find_spec("chat_sdk.adapters.teams.format")
+    assert spec is not None and spec.origin is not None
+    return Path(spec.origin).read_text(encoding="utf8")
+
+
+class TestFormatImportBoundary:
+    """Port of upstream ``format/boundary.test.ts``.
+
+    The format subpath must stay runtime-free: its own source must not
+    reference the ``microsoft_teams`` SDK, an HTTP client (``httpx`` /
+    ``aiohttp``), or the high-level adapter / chat runtime. (Upstream's
+    boundary test reads the module source and asserts it does not contain the
+    forbidden imports — runtime ``sys.modules`` inspection is deferred until
+    the ``teams/__init__.py`` lazy-subpath migration in the packaging PR.)
+    """
+
+    def test_source_does_not_import_the_sdk_runtime_or_adapter(self):
+        # Inspect only the actual import statements, so the docstring (which
+        # *mentions* these modules to describe the boundary) is not flagged.
+        import_lines = [
+            line.strip()
+            for line in _format_module_source().splitlines()
+            if line.strip().startswith(("import ", "from "))
+        ]
+        forbidden = (
+            "microsoft_teams",
+            "httpx",
+            "aiohttp",
+            "chat_sdk.adapters.teams.adapter",
+            "chat_sdk.adapters.teams.types",
+            "chat_sdk.adapters.teams.cards",
+            "chat_sdk.chat",
+        )
+        present = [f"{token} :: {line}" for line in import_lines for token in forbidden if token in line]
+        assert not present, f"format primitive imports forbidden modules: {present}"
+
+    def test_emoji_reuse_does_not_duplicate_unicode(self):
+        # The emoji map must come from chat_sdk.emoji, not be re-declared here.
+        source = _format_module_source()
+        assert "from chat_sdk.emoji import convert_emoji_placeholders" in source