Cloudflare/turnstile

@webframp/cloudflare/turnstilev2026.10.21.1· Apache-2.0· 10d agoBEHAVIORS

01README

Cloudflare Turnstile — CAPTCHA-free challenges, site widgets

02Release Notes

2026.10.21.1

Changed: The README and the apiToken description now lead with a vault. Store the token with swamp vault put cloudflare API_TOKEN and set apiToken to ${{ vault.get("cloudflare", "API_TOKEN") }}. The CLOUDFLARE_API_TOKEN environment variable still works as a fallback, but swamp does not redact it, so it is no longer recommended. The missing-token error now says the same.

Changed: Secrets returned by get_create, get_get, get_update and get_rotate_secret are now stored in a vault, and the stored resource holds a vault.get reference instead of the value. Because the model now declares secret output, swamp refuses to run any of the model's methods except list (which swamp treats as a read by its name) until a vault exists (swamp vault create local_encryption cloudflare). The README's "Secrets" section lists what each method stores.

Fixed: get_create, get_update and get_rotate_secret wrote to a resource the model does not declare, so they always failed. They now write the resource the model declares.

Upgrade note: Resources stored by earlier versions of the methods in the README's "Secrets" section may hold plaintext secrets; delete them with swamp data delete and rotate the affected credentials.

03Behaviors1

@webframp/cloudflare/turnstilev2026.10.21.1cloudflare/turnstile.ts

Global Arguments

Argument	Type	Required	Description
apiToken?	string	no	Cloudflare API token. Wire it with ${{ vault.get("cloudflare", "API_TOKEN") }}; never pass the literal token. The CLOUDFLARE_API_TOKEN environment variable is read as a fallback, but it is not redacted and is not recommended.
accountId	string	yes	Cloudflare account ID

fn list(page?: number, per_page?: number, order?: enum, direction?: enum, filter?: string)

List Turnstile Widgets

Argument	Type	Required	Description
page?	number	no
per_page?	number	no
order?	enum	no
direction?	enum	no
filter?	string	no	Filter widgets by field using case-insensitive substring matching. Format: `field:value` Supported fields: - `name` - Filter by widget name (e.g., `filter=name:login-form`) - `sitekey` - Filter by sitekey (e.g., `filter=sitekey:0x4AAA`) Returns 400 Bad Request if the field is unsupported or format is invalid. An empty filter value returns all results.

fn get_create(page?: number, per_page?: number, order?: enum, direction?: enum, filter?: string, bot_fight_mode?: unknown, clearance_level?: unknown, domains: unknown, ephemeral_id?: unknown, mode: unknown, name: unknown, offlabel?: unknown, region?: unknown)

Create a Turnstile Widget

Argument	Type	Required	Description
page?	number	no
per_page?	number	no
order?	enum	no
direction?	enum	no
filter?	string	no	Filter widgets by field using case-insensitive substring matching. Format: `field:value` Supported fields: - `name` - Filter by widget name (e.g., `filter=name:login-form`) - `sitekey` - Filter by sitekey (e.g., `filter=sitekey:0x4AAA`) Returns 400 Bad Request if the field is unsupported or format is invalid. An empty filter value returns all results.
bot_fight_mode?	unknown	no
clearance_level?	unknown	no
domains	unknown	yes
ephemeral_id?	unknown	no
mode	unknown	yes
name	unknown	yes
offlabel?	unknown	no
region?	unknown	no

fn get_get(sitekey: string)

Turnstile Widget Details

Argument	Type	Required	Description
sitekey	string	yes

fn get_update(sitekey: string, bot_fight_mode?: unknown, clearance_level?: unknown, domains: unknown, ephemeral_id?: unknown, mode: unknown, name: unknown, offlabel?: unknown, region?: unknown)

Update a Turnstile Widget

Argument	Type	Required
sitekey	string	yes
bot_fight_mode?	unknown	no
clearance_level?	unknown	no
domains	unknown	yes
ephemeral_id?	unknown	no
mode	unknown	yes
name	unknown	yes
offlabel?	unknown	no
region?	unknown	no

fn get_delete(sitekey: string)

Delete a Turnstile Widget

Argument	Type	Required	Description
sitekey	string	yes

fn get_rotate_secret(sitekey: string, invalidate_immediately?: unknown)

Rotate Secret for a Turnstile Widget

Argument	Type	Required	Description
sitekey	string	yes
invalidate_immediately?	unknown	no

Resources

list(infinite)— List Turnstile Widgets

create(infinite)— Create a Turnstile Widget

get(infinite)— Turnstile Widget Details

update(infinite)— Update a Turnstile Widget

rotate_secret(infinite)— Rotate Secret for a Turnstile Widget

04Previous Versions12

2026.10.14.1Apache-2.0(was none)Oct 14, 2026

2026.10.14.1

Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.

Upgrade note: Metadata only. No code, schema, or behavioral changes.

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.09.18.1Sep 20, 2026

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.09.17.2Sep 17, 2026

2026.09.17.2

No changes to this extension's methods. Regenerated to refresh the shared _lib/api.ts helper library after PR #427 review fixes to cfApiPaginatedCursor (used by r2, kv, durable-objects, and workers-ai, but emitted into every extension's api.ts since it's part of the shared template).

2026.09.15.1Sep 15, 2026

2026.09.15.1

Changed: Bump zod 4.4.3 → 4.6.5

2026.08.28.2

Hardened codegen: instance names sanitized against path traversal; 429 rate-limit retry with Retry-After; string schema patterns emit regex validation; output schemas passthrough unknown fields; apiToken now optional and vault-wireable with CLOUDFLARE_API_TOKEN env fallback.

2026.08.28.2Aug 28, 2026

2026.08.28.2

updated labels

2026.08.28.1Aug 28, 2026

2026.08.28.1

Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.

Upgrade note: License text only. No API, schema, or runtime behavior changed.

2026.08.26.2

Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry quality scorer can resolve dependencies and score the extension. An earlier release used a bare "zod" import-map specifier, which published but scored as unscored.

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.26.2Aug 27, 2026

2026.08.26.2

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.25.1Aug 26, 2026

2026.08.25.1

Changed: Updated labels for improved extension discoverability. Added cross-cutting category labels (security, observability, finops, infrastructure, networking, compliance, devops, ai, incident-response) where applicable.

updated labels

2026.08.24.1Aug 24, 2026

2026.08.24.1

Added: Output metadata attributes for observability.

durationMs: Method execution duration in milliseconds.
collectedBy: Extension name that produced the data.
fetchedAt: ISO 8601 timestamp when data was fetched (added to resources that previously lacked it).

2026.08.21.1Aug 22, 2026

2026.08.21.1

Changed: Errors and validation now say what went wrong and where.

Cloudflare API failures (HTTP errors and success: false API responses) now name the HTTP method and path that was attempted, in addition to the original status/message. Previously the error read only Cloudflare API error: <message>, with no indication of which endpoint the method call was hitting — now it reads Cloudflare API request failed: GET /accounts/<account>/challenges/widgets/<sitekey>: <message>. This applies to every method on this model, since they all share the same request helper.
sitekey is now validated as non-empty before any request is made. Passing an empty string previously sent a request to a malformed URL and produced a confusing 404 from Cloudflare; it now fails fast with sitekey must not be empty.

Upgrade note: No method was added, removed, or renamed. Existing callers that always pass a non-empty sitekey see no behavioral change beyond clearer error text.

2026.07.27.1Jul 27, 2026

2026.07.27.1

Fixed: Regenerated from scripts/cloudflare-codegen after two generator bugs were repaired (webframp/swamp-extensions#284).

Methods referencing an undeclared path parameter did not compile. The generator derived a method's arguments schema and execute signature from the OpenAPI parameters list, but built the request URL from the path template. Where the Cloudflare spec omits a declaration for a {placeholder} — which it does in several places — the result was a method with arguments: z.object({}) and an unused _args parameter whose body still interpolated args.<name>. Those methods failed type checking and were uncallable even if they had compiled, because the argument was never declared. Path-template placeholders are now unioned into the declared parameters, so the schema, the signature, and the body agree.
Generated tests could request a URL the mock server did not serve. Test arguments merged the request-body fixture over the path-parameter values, so a body property sharing a name with a path parameter (commonly id) substituted its own example value into the URL. The request then missed the mock and failed with Cloudflare API error: Not found. Path parameters now take precedence, matching what the generated model already does by excluding path-parameter names from the request body.

Upgrade note: No API surface change and no method was added or removed. If this extension type-checked and tested cleanly before, its behavior is unchanged and only the version moved. Extensions that previously failed deno check or deno task test now pass.

2026.07.19.1Jul 19, 2026