fix(agents): Cloud Agent Figma REST file read by cursor[bot] · Pull Request #1034 · ContextualWisdomLab/.github

cursor · 2026-08-16T15:39:18Z

Summary

#1028 records that Cloud Agents cannot complete Figma MCP OAuth and ships a whoami helper. Whoami is not file read. This successor adds the allowlisted REST file GET the file_content:read token is for, and closes the ADR/changelog/APA 7 gaps that would have let #1028 merge while still overclaiming.

scripts/ci/figma_rest_file.py GETs pinned https://api.figma.com/v1/files/{key} (optional /nodes or /images) after allowlisting the file key and node ids.
file://, http://, and api.figma.com locators never reach TLS. The token is never printed.
Operator path: store FIGMA_ACCESS_TOKEN → python3 scripts/ci/figma_rest_auth.py → python3 scripts/ci/figma_rest_file.py <file-key-or-url>.
ADR updates: AGENTS.md, CLAUDE.md, ARCHITECTURE.md, CHANGELOG.md, docs/CWL-MASTER-CONTEXT.md, and docs/doctoring/figma-cloud-agent-mcp-auth.md (## APA 7th references, retrieved 2026-08-16, Figma file-endpoints).

Supersedes #1028 at 8dd905ea. Keep #1028 draft; merge this head instead.

Developer experience

Reconstructing agents stop treating whoami as design-to-code.
Semgrep dynamic-urllib-use-detected stays inapplicable (urllib.request.urlopen is not used).
Contract tests pin the file helper, APA heading, changelog, and architecture diagram.

User experience

After the PAT secret is stored, a Cloud Agent can outline a Figma file or export PNG URLs for named frames and continue design-to-code.
Desktop/CLI still use Figma MCP Connect for the full toolset.

Test plan

tests/test_figma_rest_auth.py and tests/test_figma_rest_file.py — missing/empty token, unsafe locators, 200/400/401/403/404/503, refused file://, token never echoed, URL node-id parse, image-without-node-id fail-closed
coverage run -m pytest tests/test_figma_rest_auth.py tests/test_figma_rest_file.py (100% on both helpers)
interrogate (100% on both helpers)
Full pytest tests (1168 passed) before push
After FIGMA_ACCESS_TOKEN is added, run python3 scripts/ci/figma_rest_auth.py then python3 scripts/ci/figma_rest_file.py <real-file-url> on a Cloud Agent

cursor · 2026-08-16T15:42:01Z

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

cursor

Stale comment

Review — #1034 @ b332f91d

Verdict: COMMENT. Do not merge yet. Do not self-approve. This head closes the #1028 overclaim (whoami is not file read) with a pinned GET /v1/files/{key} helper. It is the landing vehicle. Keep #1028 and #1032 from merging in parallel.

What this head actually does

scripts/ci/figma_rest_auth.py — pinned HTTPSConnection("api.figma.com") GET /v1/me, X-Figma-Token only, 64 KiB body cap, token never printed.

scripts/ci/figma_rest_file.py — allowlisted file key (10–128 [A-Za-z0-9]) and page:node ids, then GET /v1/files/{key}?depth=N, /nodes, or /images. file://, http://, and api.figma.com locators never reach TLS. 8 MiB body cap.

ADR/changelog/APA 7 doctoring now name the file helper. That was the #1028 merge blocker.

Local evidence on this SHA (not a substitute for required GitHub checks):

pytest tests/test_figma_rest_auth.py tests/test_figma_rest_file.py — 57 passed, including the live unauthenticated /v1/me 401/403 accuracy check.

Coverage 100% statements/branches on both helpers; interrogate 100%.

Governance/changelog contract tests still pass.

FIGMA_ACCESS_TOKEN is unset in this environment, so a live file GET was not run. That is the remaining accuracy gap, not a source defect.

CodeRabbit CLI is not authenticated in this Cloud/Automation environment (coderabbit missing; prior auth login --agent browser callback times out). This is not CodeRabbit output.

No merge-blocking source defect

Allowlist, Host-header refusal, body caps, and token-free stdout match the stated contract. Official Figma file-endpoint examples use ids=1:2,1:3 and depth=2 for pages plus top-level frames (Figma, 2026c). The helper matches that shape.

Stale fail rows on gh pr checks (OpenCode, Bandit, pip-audit, CodeQL, coverage) are cancelled jobs from 8fe679d8 after this synchronize. Fresh required runs are queued/pending on b332f91d. Treat those as in-flight, not as a source regression.

Residuals (do not block this increment; do not open a fourth Figma REST PR)

Store FIGMA_ACCESS_TOKEN (plan token preferred for org fleets; PAT max 90 days). Then run python3 scripts/ci/figma_rest_auth.py and python3 scripts/ci/figma_rest_file.py '<file-key-or-url>' on a Cloud Agent. Until that secret exists, design-to-code still stops at whoami-missing.

Non-author approval + green required checks on this SHA. mergeStateStatus=BLOCKED, reviewDecision=REVIEW_REQUIRED. Reviewer seonghobae is already requested.

Next buyer gap after this lands: the GET file JSON includes styles, components, and componentSets (Figma, 2026c). summarize_file_payload drops them, so a Cloud Agent still cannot recover design tokens from the same call. Add a token/style outline on this helper after merge — do not start a competing PR.

Doc nit: doctoring cites CWE-22 for Host-header refusal. The file-key allowlist is the CWE-22 control; Host refusal is host-injection defense. Fix the citation on a later docs touch, not a reset of this SHA.

Operator next actions

Leave #1028 draft / unmerged at 8dd905ea. Leave #1032 unmerged at 5239fa65.

Wait for OpenCode / Strix / Noema / security / coverage on b332f91d. Re-run only a cancelled job on this SHA if it stays cancelled; do not push a no-op commit.

After a non-author approval and green required checks, merge this head.

After merge, store the Figma secret and use the two-step REST path. Desktop/CLI stay on Figma MCP Connect.

Figma. (2026c). Endpoints. Figma Developer Docs. Retrieved August 16, 2026, from https://developers.figma.com/docs/rest-api/file-endpoints/

_{Sent by Cursor Automation: Fix Issues}

cursor

Do not merge #1034. GitHub rejects a changes-requested review from this author on its own PR, so this is a findings review, not an approval.

Whoami-versus-file-read is fixed; the buyer job is not. The default CLI still prints a name/type tree after Figma already returned bbox, fills, characters, auto-layout, thumbnailUrl, components, and styles. A Cloud Agent that follows the documented design URL therefore cannot implement the selected frame. Desktop/CLI get_design_context remains required on this head.

Landing vehicle is #1043 (78fec778) on cursor/bc-88fdcdc4-d1c5-4cb7-806a-4f33bddc8336-b493. That successor keeps the allowlisted REST path and adds geometry, SOLID fills, TEXT, auto-layout, branch-key parsing, instance ids, honest changelog/ADR, CWE-22/918/113 citations, and a live unauthenticated /v1/files check.

Keep #1028 and #1032 draft. Do not open a fifth Figma REST PR; extend #1043 if a residual remains. Store FIGMA_ACCESS_TOKEN, then run python3 scripts/ci/figma_rest_auth.py and python3 scripts/ci/figma_rest_file.py '<figma-url>' on #1043 after it is green. This automation will not merge or self-approve.

_{Sent by Cursor Automation: Fix Issues}

cursor · 2026-08-16T15:59:40Z

+    return payload
+
+
+def outline_node(node: object, remaining_depth: int) -> dict[str, Any] | None:


outline_node drops bbox, fills, characters, auto-layout, and constraints that GET /v1/files and /v1/files/.../nodes already returned (Figma, 2026c). Default CLI output is a name/type tree. Keep a bounded subset of those fields. Repair is #1043.

cursor · 2026-08-16T15:59:41Z

+    return cleaned
+
+
+def summarize_file_payload(payload: Mapping[str, Any], outline_depth: int) -> dict[str, Any]:


summarize_file_payload ignores thumbnailUrl, components, and styles. https_image_url already exists — pass thumbnailUrl through so a Cloud Agent gets one preview without a second unpinned fetch. Repair is #1043.

cursor · 2026-08-16T15:59:41Z

+    """Return the Cloud Agent CLI for Figma file reads."""
+    parser = argparse.ArgumentParser(
+        prog="figma_rest_file.py",
+        description=(


"continue design-to-code without Figma MCP" overclaims. Match the doctoring table: REST outline + optional expiring PNG URLs. Desktop/CLI get_design_context stays the richer path. Repair is #1043.

cursor · 2026-08-16T15:59:41Z

+        "locator",
+        help="Figma file key or https://www.figma.com/design/<key>/... URL",
+    )
+    parser.add_argument(


"default 2: pages and top-level frames" is only true for GET /v1/files/:key. The documented URL-with-node-id path uses /nodes, where depth is levels under the selected node (Figma file-endpoints). Repair is #1043.

cursor · 2026-08-16T15:59:41Z

+    return key
+
+
+def validate_node_id(raw: str) -> str:


^\d+:\d+$ rejects instance ids (I12:34;56:78) that outline_node will print via identity_field. Accept the instance form for --node-id or strip those ids from the outline. Repair is #1043.

cursor · 2026-08-16T15:59:41Z

+                EXIT_INVALID_TARGET,
+            )
+        node_ids = [validate_node_id(value) for value in parse_qs(parsed.query).get("node-id", [])]
+        return validate_file_key(parts[1]), node_ids


/design/<file_key>/branch/<branch_key>/... uses parts[1] (main file). Figma's :key may be a branch key. Detect a branch segment and use that key, or fail closed. Repair is #1043.

cursor · 2026-08-16T15:59:41Z

+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).


Host-header filtering is not CWE-22, and it does not retarget TLS after HTTPSConnection("api.figma.com"). Cite CWE-22 on the file-key allowlist; cite CWE-918 for parse-don't-fetch. Update the contract pin that currently requires the string CWE-22. Repair is #1043.

cursor · 2026-08-16T15:59:41Z

+   `api.figma.com` origin, and prints a token-free JSON outline (pages and
+   top-level frames at depth 2 by default). `--images` returns HTTPS PNG
+   URLs for those nodes. `file://`, `http://`, and `api.figma.com` locators
+   are refused. Use the outline or image URLs as the next design-to-code


"Use the outline or image URLs as the next design-to-code input" sends reconstructing agents into a dead end on this head. Say: outline is navigation until design fields are kept; --images URLs expire in 30 days; get_design_context stays on Desktop/CLI. Repair is #1043.

cursor · 2026-08-16T15:59:42Z


 ### Added

+- Added Cloud Agent Figma REST helpers `scripts/ci/figma_rest_auth.py` and `scripts/ci/figma_rest_file.py` that verify `FIGMA_ACCESS_TOKEN` against pinned `GET /v1/me` and then read an allowlisted `GET /v1/files/{file_key}` (optional `/nodes` or `/images`) without printing the secret, so design-to-code continues when Figma MCP OAuth is unavailable.


"so design-to-code continues" is not true of the default outline on this head. Changelog should say whoami + allowlisted file/nodes/images GET, then name the fields actually printed. Repair is #1043.

cursor · 2026-08-16T15:59:42Z

+    )
+    assert files.main(opener=opener) == auth.EXIT_OK
+    captured = capsys.readouterr()
+    assert "Home" in captured.out or "image" in captured.out or captured.out


or captured.out makes this assertion succeed for any nonempty stdout. Assert file_name / image_urls explicitly. Add a live unauthenticated GET /v1/files 401/403/404 case parallel to whoami. Repair is #1043.

+    connection = http.client.HTTPSConnection(
+        "api.figma.com",
+        timeout=REQUEST_TIMEOUT_SECONDS,
+    )


+    connection = http.client.HTTPSConnection(
+        FIGMA_API_HOST,
+        timeout=REQUEST_TIMEOUT_SECONDS,
+    )


seonghobae · 2026-08-19T10:21:40Z

Rebased onto current main 9e9f59f3ac1e96a960c021b131d768c238f4c21a and pushed exact head f9026458. Cloud Agent Figma REST auth/file-read paths preserve secret redaction, pinned HTTPS host and request shapes, strict file-key/path validation, and no MCP fallback claim; focused verification: 57 passed.

Cursor Cloud Agents cannot complete Figma MCP OAuth. Record the 401 challenge, the official Cloud-unsupported decision, and a REST FIGMA_ACCESS_TOKEN whoami helper that never prints the secret. Co-authored-by: Seongho Bae <seonghobae@users.noreply.github.com>

Semgrep p/default flagged urllib.request.urlopen in figma_rest_auth.py as dynamic-urllib-use-detected. Open api.figma.com over TLS with a literal host and path, and refuse any other URL. Co-authored-by: Seongho Bae <seonghobae@users.noreply.github.com>

Whoami alone does not read a Figma file. Add a pinned api.figma.com GET /v1/files helper with allowlisted keys and node ids, and record the operator path in ADR, changelog, and APA 7 doctoring so Cloud Agents can continue design-to-code. Co-authored-by: Seongho Bae <seonghobae@users.noreply.github.com>

Absorb the #1032 security extras: allow only X-Figma-Token, cap whoami/file bodies, cite CWE-22 and plan tokens, and keep a live unauthenticated /v1/me accuracy check. Prefer this head over #1032. Co-authored-by: Seongho Bae <seonghobae@users.noreply.github.com>

seonghobae · 2026-08-19T15:02:18Z

Current-head evidence: rebased the Figma Cloud Agent REST auth/file-read repair onto main bbedc1a. Exact head 0135ce0. Focused Figma tests: 57 passed; git diff --check passed. The repository's pre-existing agent-mention workflow contains an actionlint-invalid queue key outside this PR's diff; it was not widened into this change. Protected hosted checks remain; no bypass used.

This was referenced Aug 16, 2026

fix(agents): Cloud Agent Figma MCP auth fallback #1028

Open

fix(ci): load Figma file pages over pinned REST #1032

Draft

seonghobae marked this pull request as ready for review August 16, 2026 15:41

seonghobae self-requested a review as a code owner August 16, 2026 15:41

cursor Bot commented Aug 16, 2026

View reviewed changes

cursor Bot mentioned this pull request Aug 16, 2026

fix(agents): keep Figma REST design fields and branch keys #1043

Draft

5 tasks

cursor Bot commented Aug 16, 2026

View reviewed changes

github-advanced-security AI found potential problems Aug 16, 2026

View reviewed changes

seonghobae force-pushed the cursor/bc-c68d4a10-4352-4ff5-9bf0-dfcc935fd222-2844 branch from b332f91 to f902645 Compare August 19, 2026 10:21

seonghobae added this to naruon Platform Roadmap Aug 19, 2026

seonghobae moved this to In Progress in naruon Platform Roadmap Aug 19, 2026

cursoragent and others added 4 commits August 19, 2026 23:57

seonghobae force-pushed the cursor/bc-c68d4a10-4352-4ff5-9bf0-dfcc935fd222-2844 branch from f902645 to 0135ce0 Compare August 19, 2026 15:00

		return payload


		def outline_node(node: object, remaining_depth: int) -> dict[str, Any] \| None:

		return cleaned


		def summarize_file_payload(payload: Mapping[str, Any], outline_depth: int) -> dict[str, Any]:


		### Added

		- Added Cloud Agent Figma REST helpers `scripts/ci/figma_rest_auth.py` and `scripts/ci/figma_rest_file.py` that verify `FIGMA_ACCESS_TOKEN` against pinned `GET /v1/me` and then read an allowlisted `GET /v1/files/{file_key}` (optional `/nodes` or `/images`) without printing the secret, so design-to-code continues when Figma MCP OAuth is unavailable.

Uh oh!

Conversation

cursor Bot commented Aug 16, 2026

Summary

Developer experience

User experience

Test plan

Uh oh!

cursor Bot commented Aug 16, 2026

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Review — #1034 @ b332f91d

What this head actually does

No merge-blocking source defect

Residuals (do not block this increment; do not open a fourth Figma REST PR)

Operator next actions

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

seonghobae commented Aug 19, 2026

Uh oh!

seonghobae commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cursor Bot left a comment •

edited

Loading

Review — #1034 @ `b332f91d`