ContextualWisdomLab
diff --git a/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/doctoring/figma-cloud-agent-mcp-auth.md‎
Lines changed: 17 additions & 3 deletions b/‎docs/doctoring/figma-cloud-agent-mcp-auth.md‎
Lines changed: 17 additions & 3 deletions
diff --git a/‎scripts/ci/figma_rest_auth.py‎
Lines changed: 39 additions & 2 deletions b/‎scripts/ci/figma_rest_auth.py‎
Lines changed: 39 additions & 2 deletions
diff --git a/‎scripts/ci/figma_rest_file.py‎
Lines changed: 5 additions & 2 deletions b/‎scripts/ci/figma_rest_file.py‎
Lines changed: 5 additions & 2 deletions
diff --git a/‎tests/test_figma_rest_auth.py‎
Lines changed: 60 additions & 3 deletions b/‎tests/test_figma_rest_auth.py‎
Lines changed: 60 additions & 3 deletions
diff --git a/‎tests/test_figma_rest_file.py‎
Lines changed: 26 additions & 3 deletions b/‎tests/test_figma_rest_file.py‎
Lines changed: 26 additions & 3 deletions
@@ -40,6 +40,7 @@ Semantic Versioning where the repository publishes a release.
 
 ### Security
 
+- Pin Figma REST calls to `http.client.HTTPSConnection("api.figma.com")`, allow only the `X-Figma-Token` header, allowlist file keys and node ids, and cap whoami/file bodies so `file://`, `Host` retargeting, and unbounded reads cannot leave the helper.
 - Reject `.github/` and `scripts/ci/` from review-thread-derived autofix path authority so an untrusted inline reviewer cannot authorize the write-capable repair agent to modify workflows, CODEOWNERS, actions, scheduler code, or CI helpers that govern its own control plane.
 - Require the model-write snapshot and exact-path allowlist to remain outside the pull-request worktree, checking both absolute and resolved locations so repository-local controls and outside-looking symlinks resolving into the repository fail closed before they can authorize or verify model changes.
 - Snapshot the complete pre-model worktree for ordinary and conflict repair and reject every model-caused created, deleted, modified, mode-changed, retargeted, ignored, dangling, directory-backed, external-link, metadata-race, or out-of-scope path before staging or push.
 
@@ -40,12 +40,19 @@ Use two disjoint auth paths:
 | Surface | Auth | Capability |
 |---|---|---|
 | Cursor Desktop / CLI | Figma MCP OAuth (`Settings → Tools & MCP → Figma → Connect`) | Full MCP toolset (`get_design_context`, `use_figma`, write-to-canvas, …) |
-| Cursor Cloud Agent | Figma personal access token in `FIGMA_ACCESS_TOKEN` | REST only: `python3 scripts/ci/figma_rest_auth.py` then `python3 scripts/ci/figma_rest_file.py <file-key-or-url>` (`X-Figma-Token` on pinned `https://api.figma.com/v1/me` and `/v1/files/{key}`) |
+| Cursor Cloud Agent | Figma personal or plan access token in `FIGMA_ACCESS_TOKEN` | REST only: `python3 scripts/ci/figma_rest_auth.py` then `python3 scripts/ci/figma_rest_file.py <file-key-or-url>` (`X-Figma-Token` only, pinned `https://api.figma.com/v1/me` and `/v1/files/{key}`) |
 
-A personal access token does **not** unlock Figma MCP on Cloud Agents. It only
-authorizes the REST API. Do not commit the token. Do not put it in
+A personal or plan access token does **not** unlock Figma MCP on Cloud Agents.
+It only authorizes the REST API. Do not commit the token. Do not put it in
 `environment.json`, workflow YAML, or chat output.
 
+Prefer a **plan access token** for organization Cloud Agent fleets
+(admin-managed, expiry up to one year; Figma, 2026a). Use a personal access
+token only when the operator is acting on their own account (maximum 90 days).
+Both kinds are stored in the same secret name. Whoami and file bodies are
+capped (64 KiB / 8 MiB). The opener refuses every header except
+`X-Figma-Token` so a `Host` override cannot retarget TLS (CWE-22; MITRE, 2026).
+
 ## Operator procedure
 
 1. **Desktop / CLI MCP (preferred for design-to-code).** In Cursor Desktop,
@@ -123,6 +130,13 @@ authorization framework* (Internet-Draft draft-ietf-oauth-v2-1). Internet
 Engineering Task Force. Retrieved August 16, 2026, from
 https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1
 
+MITRE. (2026). *CWE-22: Improper limitation of a pathname to a restricted
+directory ('Path Traversal')*. https://cwe.mitre.org/data/definitions/22.html
+
 Neilson, K. (2026, June 10). Reply in *Figma MCP shows "Forbidden" in
 Automations / Cloud Agents*. Cursor Forum. Retrieved August 16, 2026, from
 https://forum.cursor.com/t/figma-mcp-shows-forbidden-in-automations-cloud-agents/162969
+
+Sakimura, N., Bradley, J., & Agarwal, N. (2015). *Proof Key for Code Exchange
+by OAuth public clients* (RFC 7636). RFC Editor.
+https://doi.org/10.17487/RFC7636
@@ -20,11 +20,13 @@
 TOKEN_HEADER = "X-Figma-Token"
 WHOAMI_URL = "https://api.figma.com/v1/me"
 REQUEST_TIMEOUT_SECONDS = 20
+MAX_WHOAMI_BODY_BYTES = 65_536
 EXIT_OK = 0
 EXIT_MISSING_TOKEN = 2
 EXIT_REJECTED = 3
 EXIT_TRANSPORT = 4
 Opener = Callable[[str, Mapping[str, str]], tuple[int, bytes]]
+BoundedReader = Callable[[int], bytes]
 
 
 class FigmaAuthError(Exception):
@@ -55,6 +57,41 @@ def read_access_token(environ: Mapping[str, str]) -> str:
     return token
 
 
+def sanitize_request_headers(headers: Mapping[str, str]) -> dict[str, str]:
+    """Allow only ``X-Figma-Token`` so a ``Host`` header cannot retarget TLS."""
+    sanitized: dict[str, str] = {}
+    for name, value in headers.items():
+        if name.lower() != TOKEN_HEADER.lower():
+            raise FigmaAuthError(
+                f"Figma REST opener refuses header {name!s} other than "
+                f"{TOKEN_HEADER}.",
+                EXIT_TRANSPORT,
+            )
+        if not value.strip():
+            raise FigmaAuthError(
+                "Figma REST token header is empty.",
+                EXIT_TRANSPORT,
+            )
+        sanitized[TOKEN_HEADER] = value
+    return sanitized
+
+
+def read_bounded_body(read: BoundedReader, limit: int) -> bytes:
+    """Read at most ``limit`` bytes or raise ``FigmaAuthError``."""
+    if limit < 1:
+        raise FigmaAuthError(
+            "Figma REST body limit must be a positive byte count.",
+            EXIT_TRANSPORT,
+        )
+    payload = read(limit + 1)
+    if len(payload) > limit:
+        raise FigmaAuthError(
+            f"Figma REST response exceeded {limit} bytes.",
+            EXIT_TRANSPORT,
+        )
+    return payload
+
+
 def default_opener(url: str, headers: Mapping[str, str]) -> tuple[int, bytes]:
     """GET the fixed Figma whoami origin and return ``(status, body)``.
 
@@ -74,9 +111,9 @@ def default_opener(url: str, headers: Mapping[str, str]) -> tuple[int, bytes]:
         timeout=REQUEST_TIMEOUT_SECONDS,
     )
     try:
-        connection.request("GET", "/v1/me", headers=dict(headers))
+        connection.request("GET", "/v1/me", headers=sanitize_request_headers(headers))
         response = connection.getresponse()
-        return int(response.status), response.read()
+        return int(response.status), read_bounded_body(response.read, MAX_WHOAMI_BODY_BYTES)
     except OSError as exc:
         raise FigmaAuthError(
             f"Figma REST transport failed: {exc}",
 
@@ -30,6 +30,8 @@
     FigmaAuthError,
     identity_field,
     read_access_token,
+    read_bounded_body,
+    sanitize_request_headers,
 )
 
 EXIT_INVALID_TARGET = 5
@@ -48,6 +50,7 @@
 )
 DEFAULT_TREE_DEPTH = 2
 MAX_TREE_DEPTH = 8
+MAX_FILE_BODY_BYTES = 8_388_608
 FileOpener = Callable[[str, Mapping[str, str]], tuple[int, bytes]]
 
 
@@ -169,9 +172,9 @@ def default_file_opener(path: str, headers: Mapping[str, str]) -> tuple[int, byt
         timeout=REQUEST_TIMEOUT_SECONDS,
     )
     try:
-        connection.request("GET", path, headers=dict(headers))
+        connection.request("GET", path, headers=sanitize_request_headers(headers))
         response = connection.getresponse()
-        return int(response.status), response.read()
+        return int(response.status), read_bounded_body(response.read, MAX_FILE_BODY_BYTES)
     except OSError as exc:
         raise FigmaAuthError(
             f"Figma REST transport failed: {exc}",
 
@@ -135,9 +135,11 @@ def __init__(self, status: int, body: bytes) -> None:
         self.status = status
         self._body = body
 
-    def read(self) -> bytes:
-        """Return the canned body."""
-        return self._body
+    def read(self, amt: int | None = None) -> bytes:
+        """Return the canned body, honoring an optional byte limit."""
+        if amt is None:
+            return self._body
+        return self._body[:amt]
 
 
 class _FakeWhoamiConnection:
@@ -249,6 +251,61 @@ def request(self, method: str, path: str, headers: dict[str, str] | None = None)
     assert FailingConnection.last.closed is True
 
 
+def test_sanitize_request_headers_allows_only_figma_token() -> None:
+    """A Host or empty token header never reaches ``HTTPSConnection.request``."""
+    assert auth.sanitize_request_headers({}) == {}
+    assert auth.sanitize_request_headers({auth.TOKEN_HEADER: TOKEN}) == {
+        auth.TOKEN_HEADER: TOKEN
+    }
+    with pytest.raises(auth.FigmaAuthError) as host:
+        auth.sanitize_request_headers({auth.TOKEN_HEADER: TOKEN, "Host": "evil.example"})
+    assert host.value.exit_code == auth.EXIT_TRANSPORT
+    assert "Host" in str(host.value)
+    assert TOKEN not in str(host.value)
+    with pytest.raises(auth.FigmaAuthError) as blank:
+        auth.sanitize_request_headers({auth.TOKEN_HEADER: "  "})
+    assert blank.value.exit_code == auth.EXIT_TRANSPORT
+
+
+def test_read_bounded_body_rejects_oversize_and_nonpositive_limits() -> None:
+    """Response bodies cannot grow past the configured byte cap."""
+    assert auth.read_bounded_body(lambda amt: b"ok"[:amt], 8) == b"ok"
+    with pytest.raises(auth.FigmaAuthError) as oversize:
+        auth.read_bounded_body(lambda amt: b"x" * amt, 4)
+    assert oversize.value.exit_code == auth.EXIT_TRANSPORT
+    assert "4" in str(oversize.value)
+    with pytest.raises(auth.FigmaAuthError) as invalid:
+        auth.read_bounded_body(lambda amt: b"", 0)
+    assert invalid.value.exit_code == auth.EXIT_TRANSPORT
+
+
+def test_default_opener_rejects_oversize_whoami_body(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A whoami body larger than 64 KiB is a transport failure."""
+
+    class HugeConnection(_FakeWhoamiConnection):
+        """Return more bytes than the whoami cap."""
+
+        def __init__(self, host: str, timeout: int = 0) -> None:
+            """Initialize an oversized body."""
+            super().__init__(host, timeout)
+            self._body = b"x" * (auth.MAX_WHOAMI_BODY_BYTES + 1)
+
+    monkeypatch.setattr(auth.http.client, "HTTPSConnection", HugeConnection)
+    with pytest.raises(auth.FigmaAuthError) as oversize:
+        auth.default_opener(auth.WHOAMI_URL, {auth.TOKEN_HEADER: TOKEN})
+    assert oversize.value.exit_code == auth.EXIT_TRANSPORT
+    assert str(auth.MAX_WHOAMI_BODY_BYTES) in str(oversize.value)
+
+
+def test_live_unauthenticated_whoami_is_rejected_by_figma() -> None:
+    """The real ``/v1/me`` endpoint rejects a missing token with HTTP 401/403."""
+    status, body = auth.default_opener(auth.WHOAMI_URL, {})
+    assert status in {401, 403}
+    assert TOKEN not in body.decode("utf-8", errors="replace")
+    lowered = body.lower()
+    assert b"token" in lowered or b"unauthorized" in lowered or b"invalid" in lowered
+
+
 def test_helper_pins_https_origin_instead_of_dynamic_urllib() -> None:
     """Semgrep ``dynamic-urllib-use-detected`` must not apply to this helper."""
     source = Path(auth.__file__).read_text(encoding="utf-8")
 
@@ -143,9 +143,11 @@ def __init__(self, status: int, body: bytes) -> None:
         self.status = status
         self._body = body
 
-    def read(self) -> bytes:
-        """Return the canned body."""
-        return self._body
+    def read(self, amt: int | None = None) -> bytes:
+        """Return the canned body, honoring an optional byte limit."""
+        if amt is None:
+            return self._body
+        return self._body[:amt]
 
 
 class _FakeFileConnection:
@@ -197,6 +199,24 @@ def test_default_file_opener_reads_success_body(monkeypatch: pytest.MonkeyPatch)
     assert connection.closed is True
 
 
+def test_default_file_opener_rejects_oversize_body(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A file body larger than 8 MiB is a transport failure."""
+
+    class HugeConnection(_FakeFileConnection):
+        """Return more bytes than the file cap."""
+
+        def __init__(self, host: str, timeout: int = 0) -> None:
+            """Initialize an oversized body."""
+            super().__init__(host, timeout)
+            self._body = b"x" * (files.MAX_FILE_BODY_BYTES + 1)
+
+    monkeypatch.setattr(files.http.client, "HTTPSConnection", HugeConnection)
+    with pytest.raises(auth.FigmaAuthError) as oversize:
+        files.default_file_opener(files.build_request_path(FILE_KEY), {auth.TOKEN_HEADER: TOKEN})
+    assert oversize.value.exit_code == auth.EXIT_TRANSPORT
+    assert str(files.MAX_FILE_BODY_BYTES) in str(oversize.value)
+
+
 def test_default_file_opener_wraps_os_errors(monkeypatch: pytest.MonkeyPatch) -> None:
     """Network failures become ``EXIT_TRANSPORT`` without leaking the token."""
 
@@ -470,6 +490,9 @@ def test_doctoring_and_entry_docs_pin_file_read_fallback() -> None:
     assert "APA 7th references" in doctoring
     assert "Retrieved August 16, 2026" in doctoring
     assert "file-endpoints" in doctoring
+    assert "CWE-22" in doctoring
+    assert "plan access token" in doctoring
+    assert "X-Figma-Token" in changelog
     assert "scripts/ci/figma_rest_file.py" in changelog
     assert "Figma Cloud Agent REST" in architecture
     assert "FIGMA_ACCESS_TOKEN" in claude