Cloudflare/api Shield

@webframp/cloudflare/api-shieldv2026.10.21.1· Apache-2.0· 5d agoBEHAVIORS

01README

Cloudflare API Shield — schema validation, endpoint discovery, sequence rules

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.

Fixed: create_user_labels wrote to a resource the model does not declare, so it always failed. It now writes the resource the model declares.

Fixed: Create methods whose response carries no id wrote every result to one instance named created, so each call overwrote the previous one. They now name the instance by the response's id when present, else by the path parameter that scopes the call, else by a hash of the request arguments (secret arguments left out). Affected: create_api_shield_expression_templates_fallthrough, create_api_shield_endpoint_management_add_operation_to_a_zone, create_api_shield_operations_bulk_post_labels_to_operations and create_api_shield_operations_post_labels_to_operation.

Upgrade note: Results earlier versions wrote to the created instance stay there; new runs write under the new names.

03Behaviors1

@webframp/cloudflare/api-shieldv2026.10.21.1cloudflare/api_shield.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.
zoneId	string	yes	Cloudflare zone ID

fn get_api_shield_settings_retrieve_information_about_specific_configuration_properties(normalize?: boolean)

Retrieve information about specific configuration properties

Argument	Type	Required	Description
normalize?	boolean	no	Ensures that the configuration is written or retrieved in normalized fashion

fn update_api_shield_settings_set_configuration_properties(normalize?: boolean, auth_id_characteristics: unknown)

Update configuration properties

Argument	Type	Required	Description
normalize?	boolean	no	Ensures that the configuration is written or retrieved in normalized fashion
auth_id_characteristics	unknown	yes

fn get_api_shield_api_discovery_retrieve_discovered_operations_on_a_zone_as_openapi()

Retrieve discovered operations on a zone rendered as OpenAPI schemas

fn list_api_shield_api_discovery_retrieve_discovered_operations_on_a_zone()

Retrieve discovered operations on a zone

fn patch_discovered_operations()

Patch discovered operations

fn list_api_shield_api_discovery_retrieve_discovered_operation_by_id(discovery_id: string)

Retrieve a discovered operation

Argument	Type	Required	Description
discovery_id	string	yes

fn patch_discovered_operation(discovery_id: string, state?: unknown)

Patch discovered operation

Argument	Type	Required	Description
discovery_id	string	yes
state?	unknown	no

fn create_api_shield_expression_templates_fallthrough(hosts: array)

Generate fallthrough WAF expression template from a set of API hosts

Argument	Type	Required	Description
hosts	array	yes	List of hosts to be targeted in the expression

fn get_labels()

Retrieve all labels

fn get_managed_label(name: string)

Retrieve managed label

Argument	Type	Required	Description
name	string	yes

fn update_api_shield_labels_replace_operations_attached_to_managed_label(name: string, selector: unknown)

Replace operation(s) attached to a managed label

Argument	Type	Required	Description
name	string	yes
selector	unknown	yes

fn create_user_labels(items: array)

Create user labels

Argument	Type	Required	Description
items	array	yes

fn delete_user_labels(items: array)

Delete user labels

Argument	Type	Required	Description
items	array	yes

fn get_user_label(name: string)

Retrieve user label

Argument	Type	Required	Description
name	string	yes

fn put_user_label(name: string, description?: unknown, metadata?: unknown)

Update user label

Argument	Type	Required
name	string	yes
description?	unknown	no
metadata?	unknown	no

fn patch_user_label(name: string, description?: unknown, metadata?: unknown)

Patch user label

Argument	Type	Required
name	string	yes
description?	unknown	no
metadata?	unknown	no

fn delete_user_label(name: string)

Delete user label

Argument	Type	Required	Description
name	string	yes

fn update_api_shield_labels_replace_operations_attached_to_user_label(name: string, selector: unknown)

Replace operation(s) attached to a user label

Argument	Type	Required	Description
name	string	yes
selector	unknown	yes

fn list_api_shield_endpoint_management_retrieve_information_about_all_operations_on_a_zone(order?: enum)

Retrieve information about all operations on a zone

Argument	Type	Required	Description
order?	enum	no

fn api_shield_endpoint_management_add_operations_to_a_zone(items: array)

Add operations to a zone

Argument	Type	Required	Description
items	array	yes

fn delete_multiple_operations(items: array)

Delete multiple operations

Argument	Type	Required	Description
items	array	yes

fn create_api_shield_endpoint_management_add_operation_to_a_zone(endpoint: unknown, host: unknown, method: unknown)

Add one operation to a zone

Argument	Type	Required
endpoint	unknown	yes
host	unknown	yes
method	unknown	yes

fn create_api_shield_operations_bulk_post_labels_to_operations(managed?: object, selector: unknown, user?: object)

Bulk attach label(s) on operation(s) in endpoint management

Argument	Type	Required
managed?	object	no
selector	unknown	yes
user?	object	no

fn put_labels_to_operations(managed: object, selector: unknown, user: object)

Bulk replace label(s) on operation(s) in endpoint management

Argument	Type	Required	Description
managed	object	yes	Managed labels to replace for all affected operations
selector	unknown	yes
user	object	yes	User labels to replace for all affected operations

fn delete_labels_to_operations(managed?: object, selector: unknown, user?: object)

Bulk remove label(s) on operation(s) in endpoint management

Argument	Type	Required
managed?	object	no
selector	unknown	yes
user?	object	no

fn get_api_shield_endpoint_management_retrieve_information_about_an_operation(operation_id: string)

Retrieve information about an operation

Argument	Type	Required	Description
operation_id	string	yes

fn delete_an_operation(operation_id: string)

Delete an operation

Argument	Type	Required	Description
operation_id	string	yes

fn create_api_shield_operations_post_labels_to_operation(operation_id: string, managed?: array, user?: array)

Attach label(s) on an operation in endpoint management

Argument	Type	Required	Description
operation_id	string	yes
managed?	array	no	List of managed label names.
user?	array	no	List of user label names.

fn put_labels_to_operation(operation_id: string, managed?: array, user?: array)

Replace label(s) on an operation in endpoint management

Argument	Type	Required	Description
operation_id	string	yes
managed?	array	no	List of managed label names. Omitting this property or passing an empty array...
user?	array	no	List of user label names. Omitting this property or passing an empty array wi...

fn delete_labels_from_operation(operation_id: string, managed?: array, user?: array)

Remove label(s) on an operation in endpoint management

Argument	Type	Required	Description
operation_id	string	yes
managed?	array	no	List of managed label names.
user?	array	no	List of user label names.

fn get_api_shield_endpoint_management_retrieve_operations_and_features_as_open_api_schemas(host?: string)

Retrieve operations and features as OpenAPI schemas

Argument	Type	Required	Description
host?	string	no

Resources

api_shield_settings_retrieve_information_about_specific_configuration_properties(infinite)— Retrieve information about specific configuration properties

api_shield_settings_set_configuration_properties(infinite)— Update configuration properties

api_shield_api_discovery_retrieve_discovered_operations_on_a_zone_as_openapi(infinite)— Retrieve discovered operations on a zone rendered as OpenAPI schemas

api_shield_api_discovery_retrieve_discovered_operations_on_a_zone(infinite)— Retrieve discovered operations on a zone

patch_discovered_operations(infinite)— Patch discovered operations

api_shield_api_discovery_retrieve_discovered_operation_by_id(infinite)— Retrieve a discovered operation

patch_discovered_operation(infinite)— Patch discovered operation

api_shield_expression_templates_fallthrough(infinite)— Generate fallthrough WAF expression template from a set of API hosts

get_labels(infinite)— Retrieve all labels

managed_label(infinite)— Retrieve managed label

api_shield_labels_replace_operations_attached_to_managed_label(infinite)— Replace operation(s) attached to a managed label

user_labels(infinite)— Create user labels

user_label(infinite)— Retrieve user label

put_user_label(infinite)— Update user label

patch_user_label(infinite)— Patch user label

api_shield_labels_replace_operations_attached_to_user_label(infinite)— Replace operation(s) attached to a user label

api_shield_endpoint_management_retrieve_information_about_all_operations_on_a_zone(infinite)— Retrieve information about all operations on a zone

api_shield_endpoint_management_add_operations_to_a_zone(infinite)— Add operations to a zone

api_shield_endpoint_management_add_operation_to_a_zone(infinite)— Add one operation to a zone

api_shield_operations_bulk_post_labels_to_operations(infinite)— Bulk attach label(s) on operation(s) in endpoint management

put_labels_to_operations(infinite)— Bulk replace label(s) on operation(s) in endpoint management

api_shield_endpoint_management_retrieve_information_about_an_operation(infinite)— Retrieve information about an operation

api_shield_operations_post_labels_to_operation(infinite)— Attach label(s) on an operation in endpoint management

put_labels_to_operation(infinite)— Replace label(s) on an operation in endpoint management

api_shield_endpoint_management_retrieve_operations_and_features_as_open_api_schemas(infinite)— Retrieve operations and features as OpenAPI schemas

04Previous Versions12

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

2026.10.14.1

Fixed: Methods that write a singleton resource failed on current swamp with Data name 'latest' is reserved for internal use.

Changed: Singleton get and action methods now write their data under api_shield_api_discovery_retrieve_discovered_operations_on_a_zone_as_openapi-current, api_shield_endpoint_management_add_operations_to_a_zone-current, api_shield_endpoint_management_retrieve_operations_and_features_as_open_api_schemas-current, api_shield_settings_retrieve_information_about_specific_configuration_properties-current, create_user_labels-current instead of latest. Anything that read data.latest("<model>", "latest") or queried name == "latest" must use the new name.

Upgrade note: Data previously stored under latest is not migrated; re-run the method to populate the new name. No attribute schemas changed.

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

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: Error messages for API failures and invalid input are now specific instead of generic.

Every method that calls the Cloudflare API now wraps failures with the operation attempted and the zone/identifier involved (e.g. discovery_id, operation_id, name), instead of surfacing the raw SDK error with no context.
Methods that take a discovery_id, operation_id, or name now reject an empty value up front with a clear validation error, instead of sending a malformed request to the Cloudflare API and failing deep inside the HTTP call.

Upgrade note: No behavioral change for valid requests. Callers passing an empty identifier will now get an immediate, descriptive validation error instead of a Cloudflare API failure.

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