[Turnstile] Spin docs: refresh hosted prompt, helper scripts, and spin.mdx

[juleslemee]

Summary

Turnstile Spin docs: refresh the hosted agent prompt, the four deterministic helper scripts it invokes, and the spin.mdx reference page. This mirrors the canonical skill in cloudflare/skills#83.

What's in the PR

• public/turnstile/spin/prompt.md — hosted mirror of the canonical Spin skill. Bootstraps into any agent (Claude Code, Cursor, Codex, OpenCode, Copilot Chat) and drives the twelve-step wizard end-to-end. Recovery flow for an already-created widget is included in this file, not shipped separately.
• public/turnstile/spin/scripts/{auth-probe,widget-create,validate,persist-skill}.sh — four deterministic helpers the agent branches on. Each emits structured JSON on stdout, human diagnostics on stderr, and pinned exit codes. All bootstrap fetches in prompt.md verify SHA-256 pins before executing.
• src/content/docs/turnstile/spin.mdx — reference page for developers who want to set Spin up manually (dashboard, Wrangler, or AI agent). Includes a canonical siteverify snippet in two variants: Node.js (req.body[...], req.ip, res.status(403)) and Cloudflare Worker (request.formData(), CF-Connecting-IP, env.TURNSTILE_SECRET, export default { fetch(request, env) }).

Hardening (this revision)

An independent semantic review of the skill surfaced several correctness and security issues; fixes are applied here and in the companion skills PR:

• Every embedded python3 invocation runs with -I (both inline -c and - <<'PY' heredocs, plus the bootstrap loop) to prevent cwd-relative module shadowing of urllib, json, hashlib, os, re, sys.
• auth-probe.sh emits distinct network_failure and upstream_failure statuses; prompt.md Step 3 documents branches for both. Reachability problems no longer surface as scope problems.
• Post-auth recovery resumes at Step 4 (the numbered wizard) rather than skipping Steps 4-7.
• Secret-write prose (Step 9) requires git check-ignore -q <path> before writing to any .env-style file, with an explicit fallback to the platform's secret manager.
• spin.mdx canonical block split into Node.js and Cloudflare Worker forms. The previous "Node / Workers" hybrid used Express APIs (request.body[...], request.ip) that do not exist on the Worker Request.
• Delete fetch-secret.sh (superseded by the in-flow existing-widget recovery in prompt.md; no callers remain).
• Refresh fetch_spin_script SHA-256 pins in prompt.md to match the updated scripts.

Local validation

Ran locally against the merged tree:

• pnpm run check — 0 errors
• pnpm run lint — clean
• pnpm run format:core:check — all matched files use Prettier code style
• pnpm run test -- --run — 93/93 passing
• RUN_LINK_CHECK=true pnpm run build — 8701 pages built, link check clean
• Scripts: bash -n + exec bit on all four, safe smoke tests (missing_token, file_target_not_supported, empty-array rejection, unsupported-mode rejection), isolation verified by poisoning urllib.py/json.py/hashlib.py in CWD

Companion

• turnstile-spin: canonical skill refresh with independent-review hardening skills#83 — canonical SKILL.md, six framework references, the same four helper scripts, and the test doc. This docs PR mirrors it byte-for-byte on scripts.

[cloudflare-docs-bot]

Review

Reviewing new changes (commit 6cb1ef5)…

[juleslemee]

Triaged all 3 findings from the code review; all fixed in merge commit 7995c2d.

ID	Decision	Change
CR-b07f3bb2e801	Fix	Committed the 5 helper scripts (auth-probe.sh, fetch-secret.sh, persist-skill.sh, validate.sh, widget-create.sh) to public/turnstile/spin/scripts/ so the docs page is self-contained. Same content as the cloudflare/skills bundle.
CR-79e4bf260a6b	Fix	Recovery flow step 3 no longer offers 'ask user or exit' for non-no_clearance widgets. Always exits per the scope boundary at line 125 now.
CR-223fc933d2c8	Fix	Wrapped fetch+json in try/catch, added r.ok check, replaced the non-existent reject(403, 'forbidden') helper with res.status(403).send('forbidden') plus a comment about adapting to the target framework.

Also propagated the CR-79e4bf260a6b and CR-223fc933d2c8 fixes to the two companion PRs to keep the three-surface skill content in sync:

• turnstile-spin: canonical skill refresh with independent-review hardening skills#83 (commit dbcc069)
• stratus MR !40817 (commit 7410b948d35)

[juleslemee]

Triaged all 19 findings on the helper scripts; agreed with all, fixing in the pending commit.

ID	File:Line	Decision	Change
CR-22ef8f6771b1 (critical)	widget-create.sh:42	Fix	Build request body via python3 json.dumps (replaces hand-escaped JSON that broke on names/modes containing ", \, or control chars).
CR-f735353f7ad5	widget-create.sh:23	Fix	need_arg helper: guard $2 before shift so a trailing flag prints a clear usage error instead of set -u unbound-variable abort.
CR-e48c7d0bb1e9	widget-create.sh:42	Fix	Drop 2>/dev/null on the API curl. Header comment says diagnostics go to stderr; now they actually do.
CR-a9681e1b8608	widget-create.sh:49	Fix	Success output built via python3 json.dumps instead of hand-escaped echo.
CR-5fd7af1e876a	widget-create.sh:56	Fix	Error output built via python3 json.dumps; drop the tr -d '"' that was mangling legitimate quoted messages.
CR-e781359b7c28	validate.sh:27	Fix	need_arg guard.
CR-afe9e2b7b7c0	validate.sh:80	Fix	Switch to mktemp + -o $tmp + -w %{http_code} pattern; explicit HTTP status check before parsing; falls through to structured error output on 4xx/5xx.
CR-391c70408be0	validate.sh:83	Fix	Response parsed in a single python3 block with try/except; missing result or bad JSON emits a {"status":"error","check":"hostname","detail":"..."} payload with the API detail, not a traceback.
CR-c5afb0714a2f	auth-probe.sh:62	Fix	GET-based probe (which authorizes Read-only tokens) replaced with POST-invalid-payload probe. Now: 401/403/err-code-10000 → missing_scope; 400/422/other 200 → scope_ok. Tests Turnstile:Edit specifically.
CR-1f8cc5f1475c	auth-probe.sh:32	Fix	command -v wrangler guard before invocation; when wrangler is not on PATH, fall back to $CLOUDFLARE_ACCOUNT_ID. Avoids npx install-prompt hang in non-interactive envs.
CR-30730b7afe35	fetch-secret.sh:39	Fix	mktemp "${TMPDIR:-/tmp}/fetch-secret.XXXXXX" — explicit template for macOS/BSD portability. Same fix applied to all mktemp uses across the 5 scripts.
CR-2a35782321aa	fetch-secret.sh:46	Fix	Response parsed in a single python3 block using .get(..., default) for every dict access; non-JSON responses produce structured errors instead of tracebacks.
CR-e82849253dd7	fetch-secret.sh:29	Fix	need_arg guard.
CR-76a6232130e9	fetch-secret.sh:41	Fix	URL-encode account_id and sitekey via urllib.parse.quote before interpolation into the API URL. Applied consistently across widget-create, validate, and fetch-secret.
CR-03ee17a69501	persist-skill.sh:20	Fix	need_arg guard.
CR-bb0ae4241b8d	persist-skill.sh:50	Fix	Build scripts JSON list via python3 os.listdir + json.dumps. Handles filenames with quotes, backslashes, and newlines safely.
CR-1bd6e05a63d9 (suggestion)	fetch-secret.sh:43	Fix	trap 'rm -f "$tmp"' EXIT immediately after mktemp. Applied to all scripts that use temp files.
CV-1717f75f5c6a	PR-level	Fix	Updating the PR description to describe the 5 helper scripts and what they do.

All 5 scripts now pass bash -n and end-to-end smoke tests. Same content propagated to:

• turnstile-spin: canonical skill refresh with independent-review hardening skills#83 (canonical source; commit landed on branch turnstile-spin-v2-compat)
• stratus MR !40817 (inlined into spinSkillContent.ts for the dashboard's Spin flow)

[juleslemee]

Triaged the second-review findings. Skipping 2 with reasoning, fixing the other 9 in the pending commit.

Skipping

CR-04913c72363f (critical) — EXIT trap does NOT fire in $() subshells

The bot's claim: "The curl call runs inside a command substitution subshell, which inherits the trap. When that subshell exits, the trap deletes $tmp before the final python3 reads it."

That's not how bash EXIT traps work. Per the bash manual on subshell environments: "Traps caught by the shell are reset to the values inherited from the shell's parent." Command substitution runs in a subshell environment, so the parent's EXIT trap is not inherited by the $() subshell. The trap only fires when the outer script exits.

Verified locally:

$ cat > /tmp/trap-test.sh <<'END'
#!/usr/bin/env bash
set -uo pipefail
tmp=$(mktemp "${TMPDIR:-/tmp}/trap-test.XXXXXX")
trap 'echo "PARENT TRAP: rm $tmp"; rm -f "$tmp"' EXIT
echo "before curl: exists=$([ -f "$tmp" ] && echo yes || echo no)"
http_code=$(curl -sS -w "%{http_code}" -o "$tmp" https://api.cloudflare.com/client/v4 || echo "000")
echo "after curl: http_code=$http_code, exists=$([ -f "$tmp" ] && echo yes || echo no)"
[ -f "$tmp" ] && echo "size: $(wc -c < "$tmp") bytes"
END
$ bash /tmp/trap-test.sh
before curl: exists=yes
after curl: http_code=404, exists=yes
size: 105 bytes
PARENT TRAP: rm /var/folders/mq/.../trap-test.RibE8s

$tmp survives the curl subshell exit, python3 reads the response body successfully, and the trap only fires on the outer script's exit. My earlier end-to-end smoke tests also confirm this: widget-create.sh returned real HTTP 404 responses (parsed from $tmp), not the "non-JSON response" error path the bot predicted.

CR-14b4e5e6a596 (suggestion) — --path is user-supplied by design

persist-skill.sh --path <path> writes the skill bundle to a caller-chosen location. That's the tool's contract; the SKILL.md and stratus prompt tell the agent to choose the path based on the target agent runtime (.claude/skills/turnstile-spin/SKILL.md, .opencode/skills/turnstile-spin/SKILL.md, etc.). Constraining to .claude/skills/ would break support for other agent runtimes.

The bot's --path /etc/passwd example writes to /etc, which requires root; a user running as root has already opted into that. No new attack surface beyond what the caller already has file-system permission to do.

Fixing

ID	File:Line	Change
CR-8564af26b1eb	validate.sh domain parsing	[d.strip() for d in expected_csv.split(",") if d.strip()] — trims whitespace from each expected domain token.
CR-244ecc0a2bae	fetch-secret.sh:97	(errors[0] or {}).get("message") — matches the defensive pattern already used for first_code. Applied consistently across all 5 scripts.
CR-170e734f63cc	fetch-secret.sh:74	Explicit isinstance(data, dict) check after json.loads; emits structured error output when the response isn't a JSON object. Applied consistently across widget-create, validate, fetch-secret, and auth-probe.
CR-9cdbd7ec5a36	all scripts	command -v python3 guard at the top of each script; emits the script's canonical error status (missing_token / error+reason:python3_not_available etc.) and exits 1 when python3 is absent.
CR-460039bb0738 (suggestion)	all script headers	Header comments now document all three exit codes: 0 on success, 1 on failure or missing prerequisite, 2 on invalid usage.
CR-3b31dbc5640a (suggestion)	persist-skill.sh:63	Catch OSError (not just FileNotFoundError) so NotADirectoryError, PermissionError, and other listdir failures emit scripts: [] instead of a traceback. Verified locally with a scripts-is-a-file-not-a-directory case.
CR-4a512fac7815	auth-probe.sh:131	Bearer token now written to a mode-600 tempfile; curl reads it via -H "@$auth_headers". Token never appears in argv or ps output.
CR-333053976387	validate.sh:51	Turnstile secret now written to a mode-600 tempfile; curl reads it via --data-urlencode "secret@$secret_file". Secret never appears in argv. printf '%s' (no trailing newline) so the url-encoded value is exactly the secret.
CR-f14858b663da	validate.sh:120	Same tempfile-header pattern as CR-4a512fac7815.

The same 9 fixes are applied byte-for-byte to cloudflare/skills#83 (canonical) and stratus MR !40817 (inlined into spinSkillContent.ts).

[juleslemee]

Third-round docs-bot review addressed — all 4 warnings fixed, no skips this round.

Findings addressed

• CR-bb6142fcc2a0, CR-f0d5f69eb45d (widget-create.sh:71-72) — unchecked mktemp. Applied inline mktemp || { echo ...; exit 1; } guard on both $tmp and $auth_headers in widget-create.sh, and to every other mktemp call across validate.sh, fetch-secret.sh, and auth-probe.sh for consistency. On mktemp failure the scripts now emit a structured error JSON ({"status":"error","code":0,"message":"mktemp failed"} for widget-create; script-appropriate shape elsewhere) and exit non-zero, matching the existing error-JSON contract the rest of the pipeline consumes. Prior tempfiles are cleaned up before exit to avoid leaks.

• CR-b563fb92b463 (fetch-secret.sh:92) — errors[0] on non-list. Added if not isinstance(errors, list): errors = [] before the errors[0] access. Same guard added to widget-create.sh, validate.sh, and auth-probe.sh which have the same pattern, so all four are defensive against "errors": {...} or "errors": "string" shapes.

• CR-3c9c1a21df53 (persist-skill.sh) — missing command -v npx check. persist-skill.sh already had a command -v python3 guard; added the matching command -v npx guard right after it. Both return structured error JSON ({"status":"error","reason":"npx_not_available"}) and exit 1 before touching any of the downstream logic that would blow up on a missing dependency.

Verification

• bash -n clean on all 5 scripts.
• widget-create.sh with TMPDIR=/proc/does-not-exist returns the expected structured error (mktemp guard fires).
• persist-skill.sh with a PATH that excludes npx returns {"status":"error","reason":"npx_not_available"} (new guard fires).
• persist-skill.sh with npx present continues into the normal degit flow.
• The python heredoc guards are silent no-ops on the well-formed responses the API actually returns; they only kick in on malformed shapes.

Same set of changes synced to the stratus dashboard inline copy (regenerated on the token-reset branch, extracted matches canonical byte-for-byte).

Note: this PR has already used both of the auto-review passes docs-bot allocates per PR. If a codeowner wants a fresh full review over these changes, comment /full-review and it will kick another pass.

[marinaelmore]

/rebase