Skip to content

try-works/role-model / .agents/skills/turnstile-spin

turnstile-spin

Verified

Set up Cloudflare Turnstile end-to-end in a project — scan the codebase, create the widget via the Cloudflare API, deploy the managed siteverify Worker, write the frontend snippets, validate, and persist the skill. Load this when a user asks to add Turnstile, set up CAPTCHA, protect a form from bots, or fix a Turnstile integration. Mirrors developers.cloudflare.com/turnstile/spin.

templates/worker/test/unit.test.ts

View on GitHub
/**
 * Unit tests for the Worker. These don't hit Cloudflare's real siteverify —
 * see integration.test.ts for that.
 */

import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
import worker from '../src/index.js';
import type { Env } from '../src/types.js';

const TEST_ENV: Env = {
	TURNSTILE_SECRET_KEY: 'test-secret-key',
	ALLOWED_ORIGIN: '*',
};

const SITEVERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';

function mockFetchOnce(response: { status?: number; body: unknown }): void {
	vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async () => {
		return new Response(JSON.stringify(response.body), {
			status: response.status ?? 200,
			headers: { 'Content-Type': 'application/json' },
		});
	});
}

describe('CORS', () => {
	beforeEach(() => vi.restoreAllMocks());
	afterEach(() => vi.restoreAllMocks());

	it('responds to OPTIONS preflight with CORS headers', async () => {
		const res = await worker.fetch(new Request('https://w/', { method: 'OPTIONS' }), TEST_ENV);
		expect(res.status).toBe(204);
		expect(res.headers.get('Access-Control-Allow-Origin')).toBe('*');
		expect(res.headers.get('Access-Control-Allow-Methods')).toContain('POST');
	});

	it('echoes ALLOWED_ORIGIN when set explicitly', async () => {
		const env = { ...TEST_ENV, ALLOWED_ORIGIN: 'https://example.com' };
		const res = await worker.fetch(new Request('https://w/', { method: 'OPTIONS' }), env);
		expect(res.headers.get('Access-Control-Allow-Origin')).toBe('https://example.com');
	});
});

describe('Health endpoints', () => {
	it('GET / returns {ok: true, version}', async () => {
		const res = await worker.fetch(new Request('https://w/'), TEST_ENV);
		expect(res.status).toBe(200);
		const body = (await res.json()) as { ok: boolean; version: string; service: string };
		expect(body.ok).toBe(true);
		expect(body.version).toMatch(/^\d+\.\d+\.\d+$/);
		expect(body.service).toBe('turnstile-siteverify');
	});

	it('GET /health returns the same shape', async () => {
		const res = await worker.fetch(new Request('https://w/health'), TEST_ENV);
		expect(res.status).toBe(200);
		const body = (await res.json()) as { ok: boolean; version: string };
		expect(body.ok).toBe(true);
		expect(typeof body.version).toBe('string');
	});

	it('GET /healthz still returns health (legacy alias)', async () => {
		const res = await worker.fetch(new Request('https://w/healthz'), TEST_ENV);
		expect(res.status).toBe(200);
		const body = (await res.json()) as { ok: boolean };
		expect(body.ok).toBe(true);
	});
});

describe('POST / (siteverify proxy) — JSON body', () => {
	beforeEach(() => vi.restoreAllMocks());
	afterEach(() => vi.restoreAllMocks());

	it('forwards a JSON token to siteverify and returns success', async () => {
		mockFetchOnce({
			body: {
				success: true,
				hostname: 'example.com',
				challenge_ts: '2026-05-22T12:00:00Z',
				'error-codes': [],
			},
		});

		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({ token: 'abc' }),
			}),
			TEST_ENV,
		);

		expect(res.status).toBe(200);
		const body = (await res.json()) as { success: boolean; _worker?: { worker_version: string } };
		expect(body.success).toBe(true);
		expect(body._worker?.worker_version).toMatch(/^\d+\.\d+\.\d+$/);

		// Verify it called the right upstream
		expect(globalThis.fetch).toHaveBeenCalledOnce();
		expect((globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0]?.[0]).toBe(SITEVERIFY_URL);
	});

	it('passes through siteverify failure with success=false', async () => {
		mockFetchOnce({
			body: { success: false, 'error-codes': ['invalid-input-response'] },
		});

		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({ token: 'bad' }),
			}),
			TEST_ENV,
		);

		expect(res.status).toBe(200);
		const body = (await res.json()) as { success: boolean; 'error-codes': string[] };
		expect(body.success).toBe(false);
		expect(body['error-codes']).toContain('invalid-input-response');
	});

	it('returns 400 when token is missing', async () => {
		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({}),
			}),
			TEST_ENV,
		);
		expect(res.status).toBe(400);
		const body = (await res.json()) as { success: boolean; 'error-codes': string[] };
		expect(body.success).toBe(false);
		expect(body['error-codes']).toContain('missing-token');
	});

	it('returns 400 on malformed JSON', async () => {
		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: '{not json',
			}),
			TEST_ENV,
		);
		expect(res.status).toBe(400);
	});

	it('accepts cf-turnstile-response as alias for token', async () => {
		mockFetchOnce({
			body: { success: true, 'error-codes': [] },
		});
		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({ 'cf-turnstile-response': 'xyz' }),
			}),
			TEST_ENV,
		);
		expect(res.status).toBe(200);
	});
});

describe('POST / (siteverify proxy) — form body', () => {
	beforeEach(() => vi.restoreAllMocks());
	afterEach(() => vi.restoreAllMocks());

	it('accepts urlencoded body', async () => {
		mockFetchOnce({
			body: { success: true, 'error-codes': [] },
		});

		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
				body: 'token=abc',
			}),
			TEST_ENV,
		);

		expect(res.status).toBe(200);
		const body = (await res.json()) as { success: boolean };
		expect(body.success).toBe(true);
	});

	it('accepts cf-turnstile-response from form body', async () => {
		mockFetchOnce({
			body: { success: true, 'error-codes': [] },
		});
		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
				body: 'cf-turnstile-response=xyz',
			}),
			TEST_ENV,
		);
		expect(res.status).toBe(200);
	});
});

describe('Content-Type handling', () => {
	beforeEach(() => vi.restoreAllMocks());
	afterEach(() => vi.restoreAllMocks());

	it('returns 415 for unsupported content type', async () => {
		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'text/plain' },
				body: 'token=abc',
			}),
			TEST_ENV,
		);
		expect(res.status).toBe(415);
		const body = (await res.json()) as { 'error-codes': string[] };
		expect(body['error-codes']).toContain('invalid-content-type');
	});
});

describe('Path routing', () => {
	beforeEach(() => vi.restoreAllMocks());
	afterEach(() => vi.restoreAllMocks());

	it('accepts POST /siteverify as alias of POST /', async () => {
		mockFetchOnce({
			body: { success: true, 'error-codes': [] },
		});
		const res = await worker.fetch(
			new Request('https://w/siteverify', {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({ token: 'abc' }),
			}),
			TEST_ENV,
		);
		expect(res.status).toBe(200);
	});

	it('returns 404 for unknown paths', async () => {
		const res = await worker.fetch(new Request('https://w/random'), TEST_ENV);
		expect(res.status).toBe(404);
	});
});

describe('CF-Connecting-IP fallback', () => {
	beforeEach(() => vi.restoreAllMocks());
	afterEach(() => vi.restoreAllMocks());

	it('uses CF-Connecting-IP if customer did not pass remoteip', async () => {
		const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async (_url, init) => {
			const form = init?.body as FormData;
			expect(form.get('remoteip')).toBe('1.2.3.4');
			return new Response(JSON.stringify({ success: true, 'error-codes': [] }), { status: 200 });
		});

		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: {
					'Content-Type': 'application/json',
					'CF-Connecting-IP': '1.2.3.4',
				},
				body: JSON.stringify({ token: 'abc' }),
			}),
			TEST_ENV,
		);

		expect(res.status).toBe(200);
		expect(fetchSpy).toHaveBeenCalledOnce();
	});

	it('prefers explicit remoteip over CF-Connecting-IP', async () => {
		vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async (_url, init) => {
			const form = init?.body as FormData;
			expect(form.get('remoteip')).toBe('9.9.9.9');
			return new Response(JSON.stringify({ success: true, 'error-codes': [] }), { status: 200 });
		});

		await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: {
					'Content-Type': 'application/json',
					'CF-Connecting-IP': '1.2.3.4',
				},
				body: JSON.stringify({ token: 'abc', remoteip: '9.9.9.9' }),
			}),
			TEST_ENV,
		);
	});
});

describe('Hostname-mismatch defense', () => {
	beforeEach(() => vi.restoreAllMocks());
	afterEach(() => vi.restoreAllMocks());

	it('rejects success response when hostname does not match EXPECTED_HOSTNAME', async () => {
		mockFetchOnce({
			body: { success: true, hostname: 'attacker.com', 'error-codes': [] },
		});
		const env: Env = { ...TEST_ENV, EXPECTED_HOSTNAME: 'mysite.com' };
		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({ token: 'abc' }),
			}),
			env,
		);
		expect(res.status).toBe(200);
		const body = (await res.json()) as { success: boolean; 'error-codes': string[] };
		expect(body.success).toBe(false);
		expect(body['error-codes']).toContain('hostname-mismatch');
	});

	it('accepts success response when hostname matches EXPECTED_HOSTNAME', async () => {
		mockFetchOnce({
			body: { success: true, hostname: 'mysite.com', 'error-codes': [] },
		});
		const env: Env = { ...TEST_ENV, EXPECTED_HOSTNAME: 'mysite.com' };
		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({ token: 'abc' }),
			}),
			env,
		);
		const body = (await res.json()) as { success: boolean };
		expect(body.success).toBe(true);
	});

	it('does not apply hostname check when EXPECTED_HOSTNAME is unset', async () => {
		mockFetchOnce({
			body: { success: true, hostname: 'anywhere.com', 'error-codes': [] },
		});
		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({ token: 'abc' }),
			}),
			TEST_ENV,
		);
		const body = (await res.json()) as { success: boolean };
		expect(body.success).toBe(true);
	});
});

describe('Missing secret', () => {
	beforeEach(() => vi.restoreAllMocks());
	afterEach(() => vi.restoreAllMocks());

	it('returns 500 with missing-input-secret when TURNSTILE_SECRET_KEY is empty', async () => {
		const env = { ...TEST_ENV, TURNSTILE_SECRET_KEY: '' };
		const res = await worker.fetch(
			new Request('https://w/', {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({ token: 'abc' }),
			}),
			env,
		);
		expect(res.status).toBe(500);
		const body = (await res.json()) as { 'error-codes': string[] };
		expect(body['error-codes']).toContain('missing-input-secret');
	});
});
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall